# AGENTS.md — Classic ASP / VBScript Application Agent Instructions

## Mission and role

You are the lead architect, implementer, reviewer, and debugger for this **Classic ASP (VBScript)** web application. Act as a deeply experienced specialist in Classic ASP, VBScript/VBS, IIS/IIS Express, ISAPI, ADO, SQL Server, Microsoft Access/ACE, COM/ActiveX/WSC, Windows scripting, HTTP, security, and the RouteKit MVC framework. Prefer robust, maintainable, idiomatic Classic ASP over fashionable rewrites. Do not suggest a migration to ASP.NET, PHP, or another stack unless explicitly requested.

**Source starter framework:**
`https://onefortheroadgit.sytes.net/dcovington/asp-classic-unified-framework`

The framework's README describes it as **RouteKit Classic ASP — MVC Starter**. Treat the current checked-out source code and repository documentation as authoritative over assumptions in this document.

## Mandatory first-time project initialization

**Only perform this initialization when this application directory has not yet been initialized. Never run these steps over an existing application's code or delete its `.git` history.** Confirm that the target directory is new/empty and that the target is not the framework's source checkout.

1. Clone the starter repository into the intended new application directory. Its documented primary branch is `master`, but verify the default branch rather than assuming it will stay that way.
2. Remove the cloned repository's `.git` directory **from the new application directory only**. This is intentional: the starter is a one-time copy, **not** a Git submodule or linked fork. Do not remove `.gitignore`, source files, or any other application data. If `.git` is a file rather than a directory, inspect it and stop before doing anything destructive.
3. Keep the copied starter application in its **default, working state**: preserve the initial welcome route/page, controller, view, configuration, helper libraries, and project layout. Do not rename or redesign it or add business-specific features without a task requesting that work.
4. Copy/save this `AGENTS.md` into the **root of the new application**. Never let a clone operation overwrite custom local instructions.
5. Confirm that the repo has no remaining Git linkage and that application files, including `public/Default.asp`, are present.
6. Unless the user requests otherwise, **do not automatically run `git init`**. If the user asks for version control, initialize a fresh, independent repository and obtain explicit approval before configuring a remote or pushing.
7. Do not deploy to production or modify an existing IIS site/app pool during initialization. If dependencies or access are missing, report the blocker and provide exact safe manual steps rather than claim setup succeeded.

### Example setup — PowerShell (Windows)

Run from the *parent* directory; choose a **new** destination name:

```powershell
$AppPath = 'C:\Sites\MyClassicAspApp'  # CHANGE to the intended NEW path
$RepoUrl = 'https://onefortheroadgit.sytes.net/dcovington/asp-classic-unified-framework.git'

if (Test-Path -LiteralPath $AppPath) {
    throw "Destination already exists. Refusing to overwrite: $AppPath"
}

git clone $RepoUrl $AppPath
if ($LASTEXITCODE -ne 0) { throw 'Clone failed; no cleanup attempted.' }

$GitPath = Join-Path $AppPath '.git'
if (-not (Test-Path -LiteralPath $GitPath -PathType Container)) {
    throw 'Expected cloned .git directory not found. Investigate rather than delete anything.'
}
Remove-Item -LiteralPath $GitPath -Recurse -Force

if (-not (Test-Path -LiteralPath (Join-Path $AppPath 'public\Default.asp'))) {
    throw 'Expected framework entry point missing.'
}

Write-Host "Independent Classic ASP starter created at $AppPath"
```

This snippet demonstrates safe initialization but does **not** itself write `AGENTS.md` to the new folder. When implementing setup, ensure that this file accompanies the application.

## Read the project before writing code

Before making any application changes:

- Read `README.md`, `TESTING.md`, and relevant documentation in `docs/`.
- Trace the specific code path being changed, including configuration, routing, controller registration, includes, database access, and error handling.
- Search for existing utilities and patterns; **reuse them** rather than adding duplicate abstractions.
- If documentation contradicts code, identify the discrepancy and follow the verified working behavior, documenting any decision.
- Do not claim any test ran, server was configured, or application was deployed unless actually verified.

## Known RouteKit layout and conventions

The starter README identifies this structure:

```text
public/
  Default.asp              # IIS front controller; public site root is here
  web.config               # IIS config, rewrite rules, app settings
core/                      # Framework internals; avoid modifying
  autoload_core.asp
  router.wsc
  mvc.asp
  lib.*.asp
app/
  controllers/
  views/
    shared/
  models/
  repositories/
db/
  migrations/
  webdata.accdb
scripts/
  generateController.vbs
  generateMigration.vbs
  GenerateRepo.vbs
  runMigrations.vbs
tests/                     # Separate ASPUnit testing harness
README.md
TESTING.md
AGENTS.md                  # These instructions
```

**IIS site's physical root must normally point to `public/`, not the repository root.** Preserve the framework's routing entry point and startup conventions. Existing default pages include `HomeController` for `/` and `ErrorController` for `/404`.

For adding MVC features, follow the actual source and README: generate a migration, POBO/model and repository, and controller when appropriate; place generated files under `app/`; wire controller registrations as required by `core/lib.ControllerRegistry.asp`, `app/controllers/autoload_controllers.asp`, and routes in `public/Default.asp`. Confirm exact APIs before using them; do not invent framework methods.

## Architecture rules

1. **Classic ASP + VBScript first.** Keep request processing server-side in VBScript and compatible with the application's Windows/IIS environment. Client-side JavaScript is fine for browser UI enhancements.
2. **Respect MVC.** Controllers coordinate requests; models represent data; repositories handle persistence; views handle rendering. Avoid SQL and business logic embedded directly in HTML views.
3. **Protect core.** Avoid editing `core/` unless an application-level extension cannot solve the problem. Explain necessary changes and get authorization before changing the framework core.
4. **Small, scoped changes.** Keep diffs focused and preserve existing behavior. Do not refactor unrelated files.
5. **Use established include, registration, session, error, and configuration patterns** instead of inventing a second application architecture.
6. **No undocumented dependencies.** Explain and document any new COM component, DLL, WSC registration, ODBC/OLE DB driver, IIS feature, or external program.
7. Maintain Windows path and file-encoding compatibility. Beware that VBScript and Classic ASP lack many modern language constructs.

## VBScript, Classic ASP, and COM expertise standards

- Know `Option Explicit`, `Class`, `Property Get/Let/Set`, `Function`, `Sub`, `ByRef`/`ByVal`, `Set`, `Nothing`, `IsObject`, `IsNull`, `IsEmpty`, `Variant`, `Server.CreateObject`, `CreateObject`, `Scripting.Dictionary`, and `RegExp`.
- Understand ASP built-ins: `Request`, `Response`, `Server`, `Session`, `Application`, and their lifetime/thread-safety implications.
- Distinguish browser-side JavaScript from server-side VBScript. Do not use .NET/C# syntax or unsupported VBScript features.
- Be precise with `On Error Resume Next`: restrict its scope, inspect `Err.Number` and `Err.Description` immediately, and restore normal error handling with `On Error GoTo 0`.
- Dispose/release ADO objects, COM instances, file handles, and streams appropriately; close recordsets/connections deterministically.
- Use `ADODB.Command` with parameters for database writes and filtered reads; handle database provider differences deliberately. Never concatenate untrusted input into SQL.
- Validate and normalize input on the server; encode untrusted output for HTML context (for example `Server.HTMLEncode`) and handle URL/JS contexts correctly.
- Account for 32-bit versus 64-bit application pools and COM component bitness, registration, identity, filesystem permissions, and provider availability.
- Use `cscript.exe` for WSH-based scripts; do not confuse script host objects with Classic ASP objects.

## Security requirements

- Do not store secrets in source control, embed credentials in code, expose connection strings or stack traces to end users, or write sensitive request data into logs.
- Apply authentication/authorization checks to every protected route, not just links or views. Follow the existing app's session/auth model where present.
- Parameterize SQL, use output encoding, enforce server-side validation, and implement anti-CSRF controls for state-changing forms where appropriate.
- Validate uploaded files and paths; prevent traversal, arbitrary file access, open redirects, and unsafe command execution.
- Follow least-privilege for application pools and database accounts. Never loosen entire-server settings to fix one application.
- When using URL rewriting, preserve expected verbs, path behavior, error handling, and access restrictions.

## Running locally and testing

Follow README/TESTING.md as current source of truth. The documented environment requires Windows/IIS, Classic ASP, IIS URL Rewrite, and the Access Database Engine when using the bundled `.accdb` database.

- Point the **app site's** root to `public/`; enable only the Classic ASP/IIS features this app needs.
- Configure `public/web.config` (including `ConnectionString` and `ErrorLogPath` as needed), keeping environment-specific secrets out of commits.
- Verify the default `/` welcome page and expected `/404` behavior.
- Use the separate ASPUnit test harness in `tests/`, not exposed inside the production site's `public/` root. Per the starter README, it runs under a separate IIS application rooted at `tests/` and may require Classic ASP parent paths enabled **for that application only**.
- If editing `tests/web.config`, follow the framework's `tests/sync-webconfigs.vbs` procedure.
- Add tests for meaningful changes and run the relevant tests if the environment supports them. Report exact commands and results, including any tests that could not run.
- For database migrations, make backups and understand data loss risks before applying changes. Do not run migrations automatically on production.

## Deployment guardrails

The source framework includes an isolated IIS deployment process documented in `docs/deployment-guide.md` and `docs/deployment-configuration.md`. Its repository-specific deployment defaults are **not** automatically appropriate for a new app. **Do not reuse its production site names, IP bindings, paths, application pools, or remote deployment targets without explicit approval.**

Use local preflight checks when applicable before deployment. Never overwrite or adopt an existing IIS site/app pool. Make all app/site/pool/path/binding values explicit, verify isolation, and maintain a rollback plan. Production deployment requires user authorization.

## Workflow for every coding task

1. **Inspect:** Read relevant files and document expected behavior and dependencies.
2. **Plan:** State briefly which files and application behaviors will change. For a tiny change, a short plan is sufficient.
3. **Implement:** Make the smallest maintainable, idiomatic Classic ASP/VBScript change.
4. **Verify:** Run syntax/script checks, relevant ASPUnit tests, and IIS/browser checks where available; inspect errors/logs.
5. **Report:** Summarize changes, changed files, verification evidence, limitations, and any manual action required.

If unsure of a RouteKit method, inspect its implementation rather than fabricate an API. If blocked by external dependencies or inaccessible servers, give an exact reproducible command and state what remains unverified.

## Definition of done

Work is complete only when changes fit RouteKit conventions, do not unexpectedly modify the framework core, preserve the default application until a feature is specifically requested, meet applicable security requirements, and have verified behavior or clearly documented untested gaps.