feat: Host captable JSON schema at stable public URL via GitHub Pages

[acossta]

Description

Make the Captan JSON schema available at a stable, public URL hosted on GitHub Pages. This would allow users to reference the schema directly in their IDE configurations, JSON files, and validation tools without needing to generate it locally.

Current Situation

• Schema is generated dynamically via captan schema command
• Users get captable.schema.json file created locally
• No central, versioned schema URL to reference
• Each user must generate their own schema file

Proposed Solution: GitHub Pages

Host the schema on GitHub Pages with versioned URLs:

• Latest: https://acossta.github.io/captan/schema/latest/captable.schema.json
• Versioned: https://acossta.github.io/captan/schema/v0.3.0/captable.schema.json

Implementation Steps

1. Create GitHub Pages structure:

docs/
├── schema/
│   ├── latest/
│   │   └── captable.schema.json
│   ├── v0.3.0/
│   │   └── captable.schema.json
│   └── v0.4.0/
│       └── captable.schema.json

2. Generate and commit initial schema:

• Create docs/schema/ directory structure
• Generate schema using existing code
• Place in docs/schema/v0.3.0/ and docs/schema/latest/

3. Enable GitHub Pages:

• Go to Settings → Pages
• Source: Deploy from branch
• Branch: main, folder: /docs
• Save and wait for deployment

4. Update CLI to use public schema:

• When running captan init, add $schema property
• Point to: https://acossta.github.io/captan/schema/latest/captable.schema.json

5. Update release process:

• Add script: yarn build:schema
• Update release workflow to:

  - name: Generate and update schema
    run: |
      yarn build:schema
      cp schema.json docs/schema/v${{ github.event.release.tag_name }}/captable.schema.json
      cp schema.json docs/schema/latest/captable.schema.json

Benefits

For Users:

• Zero-config IDE support: Just open captable.json and get full IntelliSense
• No local schema needed: Works immediately without running captan schema
• Always up-to-date: Reference latest schema automatically
• Version pinning: Can lock to specific schema versions for stability

For IDEs:

• VS Code: Automatic schema detection via $schema property
• JetBrains IDEs: Full validation and autocomplete
• Online validators: Can validate against public URL

Example Usage

In captable.json (automatically added by CLI):

{
  "$schema": "https://acossta.github.io/captan/schema/latest/captable.schema.json",
  "version": 1,
  "company": {
    "id": "comp_123",
    "name": "Acme Inc"
    // IDE now provides autocomplete here!
  }
}

Manual VS Code configuration:

{
  "json.schemas": [
    {
      "fileMatch": ["captable.json"],
      "url": "https://acossta.github.io/captan/schema/latest/captable.schema.json"
    }
  ]
}

Release Process Updates

Add to release checklist:

1. Run yarn build:schema to generate schema
2. Copy to docs/schema/vX.Y.Z/captable.schema.json
3. Update docs/schema/latest/captable.schema.json
4. Commit: "chore: update schema for vX.Y.Z"
5. Schema will be live after merge to main

Initial Setup Tasks

1. Create docs directory structure:

mkdir -p docs/schema/latest
mkdir -p docs/schema/v0.3.0

2. Add build script to package.json:

"scripts": {
  "build:schema": "node -e \"console.log(require('./dist/schema.js').getSchemaString())\" > schema.json"
}

3. Generate initial schema:

yarn build
yarn build:schema
cp schema.json docs/schema/v0.3.0/captable.schema.json
cp schema.json docs/schema/latest/captable.schema.json

4. Update CLI to add $schema property in handleInit function

5. Configure GitHub Pages in repository settings

Acceptance Criteria

• docs/schema directory structure created
• Initial schema generated and placed in docs/schema/
• GitHub Pages enabled and serving from /docs
• Schema accessible at https://acossta.github.io/captan/schema/latest/captable.schema.json
• CLI updated to add $schema property to new captable.json files
• Release process documented to include schema updates
• VS Code successfully validates using the public URL
• Documentation updated with public schema URL

Breaking Changes

None - this is purely additive. Existing local schema generation continues to work.

Testing

1. Enable GitHub Pages
2. Verify URL works: curl https://acossta.github.io/captan/schema/latest/captable.schema.json
3. Create new captable.json with $schema property
4. Confirm VS Code provides autocomplete
5. Test with different schema versions