@3fn/core 14.1.0 → 15.0.0

package/dist/cli/sync/KeyGrain.js

@@ -0,0 +1,301 @@
+"use strict";
+/**
+ * Key-grain JSON management — Spec 123 Task 5.3 (design.md § "C7" managed-set
+ * rows `.mcp.json`, `.kiro/settings/mcp.json`, `.claude/settings.json`; the
+ * namespace rule; tasks.md § "Open inputs" 5.3 — reading = PARSED VALUES).
+ *
+ * THREE SHAPES:
+ *  - `mcpServers.<key>` in `.kiro/settings/mcp.json` (Kiro) and `.mcp.json` (CC);
+ *  - the `permissions.allow` ARRAY-ENTRY grain in `.claude/settings.json` (CC) —
+ *    an entry's identity IS its string, so the entry is both key and value.
+ *
+ * The reading, as decided:
+ *  - consumer entries survive by PARSED VALUE — we never read or write a key the
+ *    manifest did not record as emitted (a key under our prefix that we never
+ *    emitted is HERS: reported once, never managed or removed);
+ *  - when our keys are unchanged, the file is NOT WRITTEN (zero bytes change);
+ *  - when our keys change, the file is re-serialized with insertion order
+ *    preserved and 2-space indentation — whitespace may normalize on that write
+ *    only.
+ *
+ * The PACKAGE side is the emitters' own output (`shared/mcpConfig/{kiro,cc}.ts`
+ * run against a scratch directory for the manifest's `attachedTargets`), so the
+ * value `sync` compares against is exactly what `init` writes — no second copy
+ * of the emission shape to drift.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALLOW_ENTRY_PREFIX = exports.SERVER_KEY_PREFIX = exports.KEY_SURFACES = void 0;
+exports.hashKeyValue = hashKeyValue;
+exports.keyEntryId = keyEntryId;
+exports.readProjectKeys = readProjectKeys;
+exports.computePackageKeys = computePackageKeys;
+exports.classifySurfaceKeys = classifySurfaceKeys;
+exports.writeSurfaceKeys = writeSurfaceKeys;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const crypto = __importStar(require("crypto"));
+const kiro_1 = require("../shared/mcpConfig/kiro");
+const cc_1 = require("../shared/mcpConfig/cc");
+/** The three key-grain surfaces (C7 / C8). */
+exports.KEY_SURFACES = [
+    { file: '.kiro/settings/mcp.json', target: 'kiro', shape: 'mcpServers' },
+    { file: '.mcp.json', target: 'cc', shape: 'mcpServers' },
+    { file: '.claude/settings.json', target: 'cc', shape: 'permissionsAllow' },
+];
+/** The self-label for keys (the namespace rule: prefix for keys and files). */
+exports.SERVER_KEY_PREFIX = 'designerpunk-';
+exports.ALLOW_ENTRY_PREFIX = 'mcp__designerpunk-';
+/**
+ * The key-entry hash. MUST equal `init.ts`'s `ManifestBuilder.recordKey`
+ * (`sha256(JSON.stringify(value))`) — asserted by the init→sync no-op test.
+ */
+function hashKeyValue(value) {
+    return crypto.createHash('sha256').update(JSON.stringify(value)).digest('hex');
+}
+function keyEntryId(file, key) {
+    return `${file}#${key}`;
+}
+function isOurPrefix(shape, key) {
+    return shape === 'mcpServers' ? key.startsWith(exports.SERVER_KEY_PREFIX) : key.startsWith(exports.ALLOW_ENTRY_PREFIX);
+}
+/** Read every key of a surface's shape (consumer keys included — classification filters). */
+function readProjectKeys(projectRoot, surface) {
+    const abs = path.join(projectRoot, surface.file);
+    if (!fs.existsSync(abs))
+        return { kind: 'absent' };
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(abs, 'utf-8'));
+    }
+    catch (err) {
+        return { kind: 'invalid', error: err.message };
+    }
+    const keys = new Map();
+    if (surface.shape === 'mcpServers') {
+        const servers = parsed?.mcpServers;
+        if (servers && typeof servers === 'object' && !Array.isArray(servers)) {
+            for (const [k, v] of Object.entries(servers))
+                keys.set(k, v);
+        }
+    }
+    else {
+        const allow = parsed?.permissions?.allow;
+        if (Array.isArray(allow)) {
+            for (const entry of allow)
+                if (typeof entry === 'string')
+                    keys.set(entry, entry);
+        }
+    }
+    return { kind: 'ok', keys };
+}
+/**
+ * Generate the package side for `attachedTargets` by running the emitters
+ * against a scratch directory and capturing every key they record.
+ *
+ * Refuses (returns `unavailable`) when the package's template or tool manifest
+ * is missing: the emitters fail SOFT there (empty approval lists), and a
+ * soft-failed package side would read as "the package now approves nothing"
+ * and propose stripping the consumer's approvals.
+ */
+function computePackageKeys(pkgRoot, attachedTargets) {
+    const templatePath = path.join(pkgRoot, 'src/cli/templates/mcp-config.json.template');
+    const toolManifestPath = path.join(pkgRoot, 'dist/mcp/tool-manifest.json');
+    if (!fs.existsSync(templatePath)) {
+        return { kind: 'unavailable', reason: `the package's MCP config template is missing (${templatePath})` };
+    }
+    if (!fs.existsSync(toolManifestPath)) {
+        return { kind: 'unavailable', reason: `the package's tool manifest is missing (${toolManifestPath})` };
+    }
+    let template;
+    try {
+        template = JSON.parse(fs.readFileSync(templatePath, 'utf-8'));
+    }
+    catch {
+        return { kind: 'unavailable', reason: `the package's MCP config template is not valid JSON (${templatePath})` };
+    }
+    const keys = new Map();
+    for (const s of exports.KEY_SURFACES)
+        if (attachedTargets.includes(s.target))
+            keys.set(s.file, new Map());
+    if (keys.size === 0)
+        return { kind: 'ok', keys };
+    const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'dp-sync-keys-'));
+    const recorder = {
+        recordKey(relPath, key, value) {
+            const file = relPath.split(path.sep).join('/');
+            keys.get(file)?.set(key, value);
+        },
+        recordFile() {
+            /* file-grain records are not key-grain package values */
+        },
+    };
+    const originalLog = console.log;
+    console.log = () => { };
+    try {
+        if (attachedTargets.includes('kiro')) {
+            (0, kiro_1.scaffoldKiroMcpConfig)(template, path.join(scratch, '.kiro/settings/mcp.json'), recorder, scratch, pkgRoot);
+        }
+        if (attachedTargets.includes('cc')) {
+            (0, cc_1.scaffoldClaudeCodeMcpConfig)(template, scratch, recorder, pkgRoot);
+        }
+    }
+    finally {
+        console.log = originalLog;
+        fs.rmSync(scratch, { recursive: true, force: true });
+    }
+    return { kind: 'ok', keys };
+}
+/**
+ * Classify one surface. Only keys the package emits or the manifest recorded
+ * are ever classified; every other key in the file is the consumer's.
+ */
+function classifySurfaceKeys(surface, packageKeys, project, manifestEntries) {
+    const result = { surface, classified: [], yoursUnderPrefix: [], dropEntries: [] };
+    if (project.kind === 'invalid') {
+        result.invalid = project.error;
+        return result;
+    }
+    const projectKeys = project.kind === 'ok' ? project.keys : new Map();
+    const prefix = `${surface.file}#`;
+    const recorded = new Map();
+    for (const [id, entry] of Object.entries(manifestEntries)) {
+        if (entry.grain === 'key' && id.startsWith(prefix))
+            recorded.set(id.slice(prefix.length), entry);
+    }
+    const surfaceAttached = recorded.size > 0;
+    for (const [key, pkgValue] of packageKeys) {
+        const entry = recorded.get(key);
+        const pkgHash = hashKeyValue(pkgValue);
+        const inProject = projectKeys.has(key);
+        const push = (classification) => result.classified.push({ surface, key, classification, packageValue: pkgValue });
+        if (entry) {
+            if (!inProject) {
+                push('deleted-by-you');
+                continue;
+            }
+            const projHash = hashKeyValue(projectKeys.get(key));
+            if (projHash === pkgHash)
+                push('unchanged');
+            else if (projHash === entry.hash)
+                push('updated-safe');
+            else
+                push('conflict');
+        }
+        else if (inProject) {
+            // Present, under our name, never recorded as emitted → hers.
+            result.yoursUnderPrefix.push(key);
+        }
+        else {
+            push(surfaceAttached ? 'new' : 'untracked-new');
+        }
+    }
+    // Recorded keys the package no longer emits.
+    for (const [key] of recorded) {
+        if (packageKeys.has(key))
+            continue;
+        if (projectKeys.has(key)) {
+            result.classified.push({ surface, key, classification: 'removed' });
+        }
+        else {
+            result.dropEntries.push(keyEntryId(surface.file, key));
+        }
+    }
+    // Keys under our prefix that we neither emit nor recorded → hers.
+    for (const key of projectKeys.keys()) {
+        if (packageKeys.has(key) || recorded.has(key))
+            continue;
+        if (isOurPrefix(surface.shape, key))
+            result.yoursUnderPrefix.push(key);
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Writing
+// ---------------------------------------------------------------------------
+/**
+ * Set `edits` (our keys only) into the surface file. Returns true iff the file
+ * was written. No write when every edit is already present with an equal parsed
+ * value. Insertion order is preserved (an existing key keeps its position; a new
+ * key is appended); 2-space indentation.
+ */
+function writeSurfaceKeys(projectRoot, surface, edits) {
+    if (edits.length === 0)
+        return false;
+    const abs = path.join(projectRoot, surface.file);
+    let doc = {};
+    if (fs.existsSync(abs)) {
+        doc = JSON.parse(fs.readFileSync(abs, 'utf-8'));
+    }
+    let changed = false;
+    if (surface.shape === 'mcpServers') {
+        if (!doc.mcpServers || typeof doc.mcpServers !== 'object' || Array.isArray(doc.mcpServers)) {
+            doc.mcpServers = {};
+            changed = true;
+        }
+        const servers = doc.mcpServers;
+        for (const { key, value } of edits) {
+            if (key in servers && hashKeyValue(servers[key]) === hashKeyValue(value))
+                continue;
+            servers[key] = value;
+            changed = true;
+        }
+    }
+    else {
+        if (!doc.permissions || typeof doc.permissions !== 'object' || Array.isArray(doc.permissions)) {
+            doc.permissions = {};
+            changed = true;
+        }
+        const perms = doc.permissions;
+        if (!Array.isArray(perms.allow)) {
+            perms.allow = [];
+            changed = true;
+        }
+        const allow = perms.allow;
+        for (const { key } of edits) {
+            if (allow.includes(key))
+                continue;
+            allow.push(key);
+            changed = true;
+        }
+    }
+    if (!changed)
+        return false;
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, JSON.stringify(doc, null, 2) + '\n', 'utf-8');
+    return true;
+}
+//# sourceMappingURL=KeyGrain.js.map

package/dist/cli/sync/Manifest.d.ts

@@ -1,24 +1,159 @@
 /**
- * Sync manifest — tracks what was last synced for edit detection.
+ * The DesignerPunk manifest — `designerpunk.manifest.json` at the repo root.
  *
- * @see Spec 111 — Requirement 3
+ * Spec 123 Task 5.2 (design.md § "C7 … Manifest" + its tasks-round erratum;
+ * DD21). Replaces Spec 111's `.kiro/sync-manifest.json` (now the LEGACY
+ * manifest: read once, relocated, and left with a one-line pointer).
+ *
+ * - **Path**: the repo root, beside the config (DD21 — a tool-dotdir gitignore
+ *   cannot silently remove the teammate's baseline).
+ * - **Format**: stable key order and ONE ENTRY PER LINE (merge-friendly).
+ *   `serializeManifest(parseManifest(text)) === text` for every file this module
+ *   writes — the re-serialize-equals-file property.
+ * - **Fields**: `{ version, posture, installedVersion, contractHash,
+ *   attachedTargets, entries }`; each entry `{ hash, grain, origin }` keyed by
+ *   `<path>` | `<path>#<region>` | `<path>#<key>`.
+ * - **Pruning**: entries under de-managed paths are dropped with one report line
+ *   per pruned group — never classified `removed` (D-B6).
+ *
+ * @see .kiro/specs/123-consumer-distribution/design.md § "C7"
  */
-import type { ScannedFile } from './FileScanner';
+export declare const MANIFEST_FILE = "designerpunk.manifest.json";
+export declare const LEGACY_MANIFEST_PATH = ".kiro/sync-manifest.json";
+/** Manifest entry origin (design.md C7 erratum — Ada D-T-B2). */
+export type ManifestOrigin = 'copy' | 'generated' | 'emitted-key';
+export type EntryGrain = 'file' | 'region' | 'key';
+export type Posture = 'born' | 'consume';
+export type HarnessTarget = 'cc' | 'kiro';
 export interface ManifestEntry {
     hash: string;
-    managed: boolean;
+    grain: EntryGrain;
+    origin: ManifestOrigin;
+}
+export interface DesignerPunkManifest {
+    version: string;
+    posture: Posture;
+    installedVersion: string;
+    contractHash: string;
+    attachedTargets: HarnessTarget[];
+    entries: Record<string, ManifestEntry>;
 }
-export interface SyncManifest {
+/** Spec 111's manifest shape (`.kiro/sync-manifest.json`). Read-only here. */
+export interface LegacyManifest {
     version: string;
-    syncedAt: string;
-    files: Record<string, ManifestEntry>;
+    syncedAt?: string;
+    files: Record<string, {
+        hash: string;
+        managed: boolean;
+    }>;
 }
+/** The manifest-format schema marker written into `version` (distinct from `installedVersion`). */
+export declare const MANIFEST_SCHEMA_VERSION = "1";
+/**
+ * Paths `sync` no longer manages under Model B (C7 managed-set table, rows
+ * REMOVED): the consumer's token language, the types it imports, and the
+ * pre-123 component copies (now the migration surface, judged against shipped
+ * content — never against a manifest baseline).
+ */
+export declare const DEMANAGED_ROOTS: readonly ["src/tokens", "src/types", "src/components/core"];
+/**
+ * The release-1 (and pre-123) copy roots `sync` RECOGNIZES — the roots under
+ * which an earlier `init` (release 1, U1) or Spec 111 `sync` recorded package
+ * copies as `origin: 'copy'` entries. Since Task 16.5 they are NO LONGER
+ * MANAGED (C7's managed-set row "`.kiro/steering`, `governance`, `.kiro/agents`,
+ * `.kiro/skills` (package copies) — REMOVED", gate 4b): the package stops
+ * shipping them, and `sync` never classifies, updates or re-adds a copy. A
+ * `copy` entry under one of these roots is a LEGACY COPY (C7 Migration item 4):
+ * reported, and offered `--migrate-legacy` only together with `attach`
+ * (`Migration.ts` § "Legacy copies"). `.kiro/skills` is here for legacy
+ * (Spec 111) manifests only — release-1 `init` never copied it.
+ *
+ * The name and membership are pinned by Spec 119-A's relocation-integrity gate
+ * (leg A7, relabelled "the release-1 copy roots `sync` recognizes"): keep the
+ * literal on one line.
+ */
+export declare const COPY_ROOTS: readonly [".kiro/agents", ".kiro/steering", "governance", ".kiro/skills"];
 export declare function getManifestPath(projectRoot: string): string;
-export declare function loadManifest(projectRoot: string): SyncManifest | null;
-export declare function saveManifest(projectRoot: string, manifest: SyncManifest): void;
+export declare function getLegacyManifestPath(projectRoot: string): string;
+/** Normalize a path to the manifest's forward-slash form. */
+export declare function toManifestPath(relPath: string): string;
+/** True iff `relPath` equals `root` or sits under it (forward-slash compare). */
+export declare function isUnder(relPath: string, root: string): boolean;
+/** The file path an entry key names (`<path>`, `<path>#<region>`, `<path>#<key>` → `<path>`). */
+export declare function entryFilePath(entryKey: string): string;
+/**
+ * Parse manifest text. Throws on invalid JSON or a missing required field —
+ * a corrupt manifest is reported, never silently treated as "first sync"
+ * (Spec 111 did the latter; under Model B that would re-baseline edits away).
+ */
+export declare function parseManifest(text: string): DesignerPunkManifest;
+/**
+ * Serialize with a stable top-level key order, entries sorted by key
+ * (code-unit order — locale-independent), and ONE ENTRY PER LINE.
+ */
+export declare function serializeManifest(manifest: DesignerPunkManifest): string;
+export type ManifestLoad = {
+    kind: 'absent';
+} | {
+    kind: 'ok';
+    manifest: DesignerPunkManifest;
+    text: string;
+} | {
+    kind: 'corrupt';
+    error: string;
+};
+export declare function loadManifest(projectRoot: string): ManifestLoad;
+export declare function loadLegacyManifest(projectRoot: string): LegacyManifest | null;
+/** Write the manifest. Returns true iff bytes changed (no write when identical). */
+export declare function saveManifest(projectRoot: string, manifest: DesignerPunkManifest): boolean;
+export interface PrunedGroup {
+    /** The de-managed root the entries sat under (e.g. `src/tokens`). */
+    root: string;
+    count: number;
+}
+/**
+ * Drop entries under DEMANAGED_ROOTS from `entries` (in place). Returns one
+ * group per root with a nonzero count, in DEMANAGED_ROOTS order.
+ */
+export declare function pruneDemanaged(entries: Record<string, ManifestEntry>): PrunedGroup[];
+/**
+ * Design catalog row "managed manifest pruned (D-B6)":
+ * `no longer managing <N> files under <paths> — under the current contract they are yours (not removed from disk)`
+ */
+export declare function prunedMessage(count: number, paths: string): string;
+/**
+ * The clause appended to the `src/types` pruning line (Ada D-T-A5: a pre-123
+ * consumer's copied `src/tokens` still imports `../types` relatively, so the
+ * de-managed `src/types` must not read as "safe to delete"). Authored at Task
+ * 5.5 (Ada); text carried unchanged from Lina's draft — it already said the
+ * right thing.
+ */
+export declare const SRC_TYPES_PRUNE_CLAUSE = " \u2014 keep them: your token tier still imports them through relative ../types paths, so deleting src/types breaks generate";
+/** One report line per pruned group; the `src/types` line carries the D-T-A5 clause. */
+export declare function pruneReportLines(groups: PrunedGroup[]): string[];
+export interface LegacyConversion {
+    manifest: DesignerPunkManifest;
+    pruned: PrunedGroup[];
+}
+/**
+ * Convert a Spec 111 manifest. Copy-root entries become `{ grain: 'file',
+ * origin: 'copy' }` (their hash is the Spec 111 baseline — correct for these
+ * untransformed files); entries under DEMANAGED_ROOTS are pruned with a report.
+ * `attachedTargets` is EMPTY: no pre-123 install was attached, so no generated
+ * surface is managed until `attach` records one (U2).
+ *
+ * The legacy `version` is the LAST SYNC — never the copy version and never the
+ * installed version (C7 step 2) — so it is not carried into the new manifest.
+ */
+export declare function convertLegacyManifest(legacy: LegacyManifest, installedVersion: string): LegacyConversion;
 /**
- * Bootstrap a manifest from current project state.
- * Records each project file's current hash as baseline — no conflicts on first sync.
+ * The one-line pointer left in the legacy file for one release (C7 step 1).
+ * JSON has no comment syntax, so the pointer is a leading `"//"` member; the
+ * rest of the legacy content is preserved byte-for-byte in meaning.
  */
-export declare function bootstrapManifest(projectFiles: ScannedFile[], version: string): SyncManifest;
+export declare const LEGACY_POINTER_TEXT = "moved to designerpunk.manifest.json at the repo root by 'npx designerpunk sync' \u2014 this file is no longer read and can be deleted after the next release";
+/** Returns true iff the pointer was written (false when already present or unreadable). */
+export declare function writeLegacyPointer(projectRoot: string): boolean;
+/** True iff the legacy file already carries the relocation pointer. */
+export declare function legacyHasPointer(projectRoot: string): boolean;
 //# sourceMappingURL=Manifest.d.ts.map