ms access vcs
- Repo stars 15
- Author repo ms-access-ai-skill
- Domain
- Data
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 88 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @paramountsoftware · no license declared
- Token usage
- Lean
- Setup complexity
- Plug-and-play
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- No explicit requirements detected
- Detected file/system behavior
-
- Read-only
- Write / modify
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
# Microsoft Access VCS Project Guide
Rules and gotchas for programmatically editing Access objects exported by VCS 4.x. Violations cause silent corruption or `Error 2128` on import via `LoadComponentFromText`.
## Reference Files
Read the relevant reference file before working on a specific object type:
| When working on... | Read this reference |
|---|---|
| Form `.bas` layout or form controls | `references/forms.md` |
| Report `.bas` layout, sections, or sorting/grouping | `references/reports.md` |
| Images in forms or reports (add, replace, convert from OLE) | `references/images.md` |
| Conditional formatting (forms or reports) | `references/conditional-formatting.md` |
| Queries (`.bas` + `.sql`) | `references/queries.md` |
| Tables, relationships, or ODBC connections | `references/tables-and-relationships.md` |
| VBA modules (`.bas`) or code-behind (`.cls`) | `references/vba.md` |
| Project config files (vcs-options, vcs-index, etc.) | `references/project-config.md` |
| Macros, shared images, or import/export specs | `references/other-objects.md` |
## Project Overview
A VCS-exported Access project lives in `<DatabaseName>.accdb.src/`. The directory name **must** match the `.accdb` filename with `.src` appended.
### File Pairing Rules
| Object Type | Files | Notes |
|-------------|-------|-------|
| Form | `.bas` + optional `.cls` + optional `.json` | `.bas` = layout, `.cls` = VBA code-behind (omitted if no code), `.json` = print settings |
| Report | `.bas` + optional `.cls` + optional `.json` | Same binary text format as forms, `.cls` = VBA code-behind (uncommon but valid), `.json` = print settings |
| Query | `.bas` + `.sql` | `.bas` = metadata/designer state, `.sql` = SQL text. Always paired |
| Module | `.bas` | Standard VBA module |
| Relationship | `.json` | Foreign key definition, join type, referential integrity |
| Linked Table | `.json` | Connection string, source table, attributes |
| Local Table | `.xml` | XSD schema defining columns, data types, indexes. For tables stored inside the .accdb |
| Macro | `.bas` | Access macro actions (not VBA). Simpler binary text format |
| Shared Image | `.json` + image file | `.json` = metadata (name, extension, hash), paired with actual image file (`.png`, `.jpg`, etc.) |
| Import/Export Spec | `.json` | Column definitions, delimiters, data types |
| Theme | `.thmx` | Office theme (binary OOXML archive — do not edit) |
When deleting an object, delete ALL its associated files plus its entry in `vcs-index.json`.
### Encoding
All JSON configuration files and `.sql` files use **UTF-8 with BOM** (byte order mark `EF BB BF`). The BOM must be preserved when editing. Binary text `.bas` files (forms, reports, macros) also use UTF-8 with BOM. `.bas`, `.cls`, and tbldef/relation `.json` files additionally use **CRLF** line endings (enforced via `.gitattributes`).
**Creating a new file from scratch:** standard write tools (including Claude's `Write` tool, `echo`, `cat <<EOF`) silently produce UTF-8 *without* BOM and use **LF** endings — this will corrupt the import. To create a new VCS file, emit the bytes explicitly:
```bash
printf '\xEF\xBB\xBF{\r\n "Info": { ... }\r\n}\r\n' > path/to/new-file.json
```
Verify after writing: `od -c -N 5 path/to/new-file.json` should show `357 273 277` (the BOM) as the first three bytes, and the file should contain `\r` before each `\n`. *Editing* an existing file with `Edit`/`Read` preserves the original encoding — the BOM-stripping issue only applies to brand-new files created via `Write`.
## Safe Deletion Checklist
Before deleting any Access object:
1. **Search for references** in all `.cls`, `.bas`, `.sql` files. Objects may be referenced by:
- VBA code (`DoCmd.OpenForm`, `DoCmd.OpenReport`, `DoCmd.OutputTo`)
- Query SQL (`FROM tableName`, subreport `SourceObject`)
- Form RecordSource properties
- DLookup expressions
2. **Check for name collisions.** Objects with similar names may serve completely different purposes (e.g., an active report and a dead integration table that share a prefix).
3. **Delete all paired files** (.bas + .sql, .bas + .cls + .json, etc.)
4. **Remove from config files:** vcs-index.json, db-connection.json, hidden-attributes.json
5. **Renumber TabIndex** values in any form/report section where a control was removed
6. **Test import** in Access after changes
## Common Pitfalls
- **Commented-out code referencing kept objects:** Leave commented VBA lines alone if they reference objects you're keeping.
- **db-connection.json:** Must contain only one connection entry matching the canonical ODBC connection string used by all linked tables and pass-through queries. Never introduce plaintext passwords or user-specific credentials.
Sections and files
Listed in source order.
sections -> Reference Files → Project Overview → File Pairing Rules → Encoding → Safe Deletion Checklist → Common Pitfalls
terms -> must · UTF-8 with BOM · CRLF · Creating a new file from scratch · LF · Search for references · Check for name collisions. · Delete all paired files
files/cmd -> Error 2128 · LoadComponentFromText · .bas · references/forms.md · references/reports.md · references/images.md · references/conditional-formatting.md · .sql
body sha256 -> 12c52230ad16
Reference Files
Read the relevant reference file before working on a specific object type: When working on... · Read this reference Form
.baslayout or form controls ·references/forms.mdReport.baslayout, sections, or sorting/grouping ·references/reports.mdImages in forms or reports (add, replace, convert from OLE) ·references/images.mdProject Overview
A VCS-exported Access project lives in
<DatabaseName>.accdb.src/. The directory name must match the.accdbfilename with.srcappended.File Pairing Rules
Object Type · Files · Notes Form ·
.bas+ optional.cls+ optional.json·.bas= layout,.cls= VBA code-behind (omitted if no code),.json= print settings Report ·.bas+ optional.cls+ optional.json· Same binary text format as forms,.cls= VBA code-behind (uncommon but valid),.json= print settings Query ·.bas+.sql·.bas= metadata/designer state,.sql= SQL text. Always pairedEncoding
All JSON configuration files and
.sqlfiles use UTF-8 with BOM (byte order markEF BB BF). The BOM must be preserved when editing. Binary text.basfiles (forms, reports, macros) also use UTF-8 with BOM..bas,.cls, and tbldef/relation.jsonfiles additionally use CRLF line endings (enforced via.gitattributes). Creating a new file from scratch: standard write tools (including Claude'sWritetool,echo,cat <<EOF) silently produce UTF-8 without BOM and use LF endings — this will corrupt the import. To create a new VCS file, emit the bytes explicitly:Safe Deletion Checklist
Before deleting any Access object: Search for references in all
.cls,.bas,.sqlfiles. Objects may be referenced by: VBA code (DoCmd.OpenForm,DoCmd.OpenReport,DoCmd.OutputTo) Query SQL (FROM tableName, subreportSourceObject) Form RecordSource properties