feat(cli): PM-unified github store layout with shallow clones

[amondnet]

Summary

Refactors the <ASK_HOME>/github/ store to use a PM-unified nested layout
(github.com/<owner>/<repo>/<tag>/) with independent shallow clones, replacing
the legacy bare-clone subsystem that had five structural correctness defects.

Key changes

• Store layout: github/<host>/<owner>/<repo>/<tag>/ — each entry is an independent shallow clone with .git/ stripped and commit SHA captured
• Schema: strict mutable-ref validation (rejects main/master/HEAD/etc.), ResolvedEntry.commit and FetchResult.storeSubpath fields
• Source: cloneAtTag with v-prefix fallback (never emits vv1.2.3), docsPath traversal guard hardened with realpathSync
• Store integrity: verifyEntry guard on store-hit short-circuit, quarantineEntry for corrupt entries, STORE_VERSION file
• Legacy migration: detection of old github/db/ and github/checkouts/ dirs, ask cache clean --legacy command
• CLI flags: --allow-mutable-ref to bypass strict ref validation
• Link/ref mode: storeSubpath support so symlinks point at the docs subdirectory, not the repo root

Track

• Idea: .please/docs/ideas/github-store-pm-unified.md
• Track: .please/docs/tracks/active/github-store-pm-unified-20260411/

Test plan

• Unit tests for githubStorePath segment validation
• Unit tests for strict/lax AskJsonSchema ref validation
• Integration tests for saveDocs symlink/copy fallback
• Integration tests for concurrent install and .git/ strip
• Store-hit guard, vv-ref prevention, and quarantineEntry invariant tests
• docsPath traversal guard tests (symlink bypass prevention)

[cloudflare-workers-and-pages]

Deploying ask-registry with    Cloudflare Pages

Latest commit:	bf8f1df
Status:	🚫  Build failed.

View logs

[cubic-dev-ai]

No issues found across 1 file

_{Auto-approved: This is a documentation-only change adding an architectural proposal/one-pager to the docs folder. It has no impact on source code or production logic.}

Architecture diagram

sequenceDiagram
    participant CLI as CLI (ask install)
    participant VAL as Validation Layer
    participant GS as GitHub Source
    participant Git as Git Binary
    participant Store as Store (~/.ask/github/...)

    Note over CLI,Store: NEW: Proposed Unified Store Flow

    CLI->>VAL: Validate package ref
    alt NEW: Ref is mutable (main, master, etc.)
        VAL-->>CLI: Reject (Error: Suggest tag/SHA or --allow-mutable-ref)
    else Ref is tag-like or SHA
        VAL-->>CLI: Proceed
    end

    CLI->>GS: fetch(owner, repo, ref)
    
    Note over GS,Store: CHANGED: Check nested path <host>/<owner>/<repo>/<tag>
    GS->>Store: Check if path exists
    
    alt Store Hit
        GS->>Store: NEW: verifyEntry(path)
        alt Integrity Check Fails
            GS->>Store: NEW: Quarantine corrupt entry
        else Integrity Check Passes
            GS-->>CLI: Return FetchResult (with storeSubpath)
        end
    end

    opt Store Miss or Verification Failed
        GS->>Git: CHANGED: Shallow clone --depth 1 --branch <tag>
        Git-->>GS: Clone to tmpDir
        GS->>GS: NEW: Remove .git/ metadata
        GS->>Store: Atomic move tmpDir to nested store path
    end

    GS-->>CLI: Return FetchResult (NEW: includes storeSubpath)
    
    Note over CLI,Store: Materialization Phase
    alt Link Mode
        CLI->>Store: CHANGED: Symlink target + storeSubpath
    else Ref Mode
        CLI->>Store: CHANGED: Resolve Agents path + storeSubpath
    end

Loading

[codecov]

Codecov Report

❌ Patch coverage is 84.77011% with 53 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
packages/cli/src/store/cache.ts	76.53%	23 Missing ⚠️
packages/cli/src/sources/github.ts	90.66%	14 Missing ⚠️
packages/cli/src/install.ts	72.00%	7 Missing ⚠️
packages/cli/src/store/index.ts	87.27%	7 Missing ⚠️
packages/cli/src/storage.ts	75.00%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!

[cubic-dev-ai]

0 issues found across 4 files (changes from recent commits).

_{Auto-approved: This PR is strictly limited to documentation and project tracking (idea doc, spec, and plan) within the .please/docs directory. No source code or production logic is modified.}

[cubic-dev-ai]

2 issues found across 17 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/cli/test/cli/commands.test.ts">

<violation number="1" location="packages/cli/test/cli/commands.test.ts:103">
P3: This test swallows the only signal that mutable-ref validation succeeded, so it can pass even if `--allow-mutable-ref` regresses. Assert a post-install effect instead of ignoring the command result.</violation>
</file>

<file name="packages/cli/test/storage.test.ts">

<violation number="1" location="packages/cli/test/storage.test.ts:94">
P2: The EPERM fallback assertion expects `README.md`, but copy mode only creates the passed-in files plus `INDEX.md`. This will fail on systems where symlink creation falls back.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

1 issue found across 13 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="README.md">

<violation number="1" location="README.md:307">
P3: The new store-model sentence is inaccurate: not all source kinds use `<identity>@<version>` paths. This can mislead users troubleshooting cache paths.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

1 issue found across 6 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/cli/src/sources/github.ts">

<violation number="1" location="packages/cli/src/sources/github.ts:327">
P1: The new docsPath guard is bypassable via symlinks because it uses `path.resolve` instead of realpath resolution.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

0 issues found across 4 files (changes from recent commits).

_{Requires human review: Large structural refactor of the GitHub storage layout, introduction of legacy migration logic, and changes to core installation and validation paths require human review.}