fiko-ai-context-sync

CLI that syncs the fiko-ai-context bundle (CLAUDE.md, .ai/*, git hooks) into a consumer service repo. Ported from fiko-shared-types/scripts/distribute-types.js's proven copy/clean/CRLF-safe approach, adapted from a push model (run from the source repo) to a pull model (run from inside each consumer, since .ai/* isn't an npm dependency of each service and CI runners only ever check out one repo at a time).

Status: prototype, not yet published to npm. Consumer repos reference it via a local file: link during the fiko-core-service rollout prototype; see fiko-ai-context/README.md's "Deferred"/handoff notes for what's left before a real npm publish.

Commands

fiko-ai-context-sync pull [--quiet] [--source <path>] [--repo-url <url>] [--ref <tag|branch>]
fiko-ai-context-sync check [--source <path>] [--repo-url <url>] [--ref <tag|branch>]
fiko-ai-context-sync install-hooks

• pull — the main sync operation. Copies .ai/ and githooks/ from the resolved source into the current repo, merges CLAUDE.md (preserving the repo's own "Repo-local preface" below the sync markers), writes .ai-context-version, and calls install-hooks. Never exits non-zero and never throws — any failure (network, missing source, git error) is logged to stderr as a warning and the existing context is left in place. This is what makes it safe in postinstall: a Docker build layer that runs pnpm install before COPY . . has no .git directory present, so pull detects that and no-ops immediately, rather than breaking the build.
• check — compares the local .ai-context-version to the latest source VERSION and exits 1 on mismatch. Used by CI (though CI implements the same comparison directly in shell rather than depending on this package — see fiko-ai-context's check_ai_context_version job — so a registry outage never blocks a pipeline). Useful locally as a pre-flight check.
• install-hooks — idempotently points core.hooksPath at .githooks. Warns (doesn't override) if core.hooksPath is already set to something else. Called automatically at the end of pull.

Source resolution order

1. --source <path> — explicit override (local testing).
2. ../fiko-ai-context sibling folder relative to cwd — fast path for local dev in this org's folder-of-repos layout, no network needed.
3. A cached shallow clone at ~/.cache/fiko-ai-context, fetched to the highest semver tag on the remote (falls back to main if no tags exist yet).

Wiring into a consumer repo

// package.json
{
  "scripts": {
    "sync:ai-context": "fiko-ai-context-sync pull",
    "postinstall": "fiko-ai-context-sync pull --quiet"
  },
  "devDependencies": {
    "fiko-ai-context-sync": "^0.1.0"
  }
}

Plus .githooks/post-merge / .githooks/post-checkout (synced in from fiko-ai-context/githooks/, wired via core.hooksPath once install-hooks has run at least once).