@aperant/framework 0.6.2

package/dist/cli/artifacts/self-stage.mjs

@@ -0,0 +1,167 @@
+/**
+ * @internal
+ * self-stage.mjs — self-staging wrapper for committable .aperant/ writes (C56 B4).
+ *
+ * Intended consumers: state-mutating CLI verbs in roadmap.mjs, task.mjs,
+ * pr-review.mjs, features-audit.mjs. Call this helper just before returning
+ * the success envelope so the caller's next commit picks up the writes.
+ *
+ * Contract:
+ *   - Intersect changed paths with classification.filterCommittable.
+ *   - Enforce the task's outputs allowlist (R11). Paths outside the allowlist
+ *     are dropped with reason='outputs-violation'.
+ *   - Dedupe against `git diff --cached --name-only` so we never re-stage.
+ *   - Shell `git add -f <paths>` scoped to projectDir (not worktree — the
+ *     writes land under `.aperant/` which always lives in the main repo).
+ *   - Best-effort: any git failure is caught and surfaced as a warning. The
+ *     helper NEVER throws; callers keep working.
+ *
+ * Why `-f`? Some `.aperant/*` paths are covered by a `.gitignore` rule today
+ * (e.g. `.aperant/tasks/**` is gitignored by design). When a subset of those
+ * paths is committable (e.g. a round snapshot under pr-reviews), `-f` is
+ * required or `git add` refuses silently.
+ */
+import { execFileSync } from 'node:child_process';
+import { isAbsolute, relative, resolve } from 'node:path';
+import { findOutputsViolations } from '../task/outputs-guard.mjs';
+import { ARTIFACT_CLASS, classifyArtifactPath } from './classification.mjs';
+/**
+ * Self-stage the committable subset of `changedPaths`.
+ *
+ * @param {string} projectDir absolute path to repo root where `.aperant/` lives.
+ * @param {string[]} changedPaths repo-relative paths that were just written
+ *   by the caller. Absolute paths are tolerated — they're relativized here.
+ * @param {{ outputs?: readonly string[] | null }} [opts]
+ * @returns {{ staged: string[], skipped: Array<{ path: string, reason: string }>, warnings: string[] }}
+ * @internal
+ */
+export function selfStageCommittableWrites(projectDir, changedPaths, opts = {}) {
+    const warnings = [];
+    const skipped = [];
+    const staged = [];
+    if (!projectDir || typeof projectDir !== 'string') {
+        return { staged, skipped, warnings: ['self-stage: missing projectDir'] };
+    }
+    if (!Array.isArray(changedPaths) || changedPaths.length === 0) {
+        return { staged, skipped, warnings };
+    }
+    const absRoot = resolve(projectDir);
+    const rels = [];
+    for (const raw of changedPaths) {
+        if (typeof raw !== 'string' || raw.length === 0)
+            continue;
+        const rel = toRepoRelative(raw, absRoot);
+        if (!rel) {
+            skipped.push({ path: raw, reason: 'outside-project' });
+            continue;
+        }
+        rels.push(rel);
+    }
+    // Step 1: committable filter via classification.
+    const committable = [];
+    for (const p of rels) {
+        const cls = classifyArtifactPath(p);
+        if (cls === ARTIFACT_CLASS.COMMITTABLE)
+            committable.push(p);
+        else if (cls === ARTIFACT_CLASS.EPHEMERAL)
+            skipped.push({ path: p, reason: 'ephemeral' });
+        else
+            skipped.push({ path: p, reason: 'unclassified' });
+    }
+    if (committable.length === 0) {
+        return { staged, skipped, warnings };
+    }
+    // Step 2: enforce outputs allowlist (R11). Missing/empty allowlist means
+    // "no restriction" here (the roadmap sync helper treats it differently —
+    // `['**']` as explicit unlimited; empty means reject. Self-stage is
+    // called post-mutation by callers that may not know the task allowlist,
+    // so we take a gentler stance: when `outputs` is falsy, pass through).
+    let afterOutputs = committable;
+    if (Array.isArray(opts.outputs) && opts.outputs.length > 0) {
+        const violations = new Set(findOutputsViolations(opts.outputs, committable));
+        afterOutputs = [];
+        for (const p of committable) {
+            if (violations.has(p))
+                skipped.push({ path: p, reason: 'outputs-violation' });
+            else
+                afterOutputs.push(p);
+        }
+    }
+    if (afterOutputs.length === 0) {
+        return { staged, skipped, warnings };
+    }
+    // Step 3: dedupe against already-staged index snapshot.
+    let alreadyStaged = new Set();
+    try {
+        const out = execFileSync('git', ['diff', '--cached', '--name-only', '-z'], {
+            cwd: absRoot,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        alreadyStaged = new Set(out.split('\0').filter((s) => s.length > 0));
+    }
+    catch (err) {
+        warnings.push(`self-stage: git diff --cached failed (${stringifyErr(err)})`);
+    }
+    const toStage = [];
+    for (const p of afterOutputs) {
+        if (alreadyStaged.has(p))
+            skipped.push({ path: p, reason: 'already-staged' });
+        else
+            toStage.push(p);
+    }
+    if (toStage.length === 0) {
+        return { staged, skipped, warnings };
+    }
+    // Step 4: `git add -f <paths>`. Scoped to projectDir. Batch-adds in one call.
+    try {
+        execFileSync('git', ['add', '-f', '--', ...toStage], {
+            cwd: absRoot,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        for (const p of toStage)
+            staged.push(p);
+    }
+    catch (err) {
+        warnings.push(`self-stage: git add -f failed for ${toStage.length} path(s): ${stringifyErr(err)}`);
+        for (const p of toStage)
+            skipped.push({ path: p, reason: 'git-add-failed' });
+    }
+    return { staged, skipped, warnings };
+}
+/**
+ * Relativize a path against the project root. Returns `null` when the path
+ * lives outside the project (we refuse to stage those).
+ *
+ * @param {string} raw
+ * @param {string} absRoot
+ * @returns {string | null}
+ * @internal
+ */
+function toRepoRelative(raw, absRoot) {
+    let rel = raw;
+    if (isAbsolute(raw)) {
+        const r = relative(absRoot, raw);
+        if (r.startsWith('..'))
+            return null;
+        rel = r;
+    }
+    // Normalize `./` and backslashes.
+    rel = rel.replace(/\\/g, '/').replace(/^\.\//, '');
+    if (rel.startsWith('../'))
+        return null;
+    if (rel.length === 0)
+        return null;
+    return rel;
+}
+/**
+ * @param {unknown} err
+ * @returns {string}
+ * @internal
+ */
+function stringifyErr(err) {
+    if (err && typeof err === 'object' && 'message' in err)
+        return String(err.message);
+    return String(err);
+}
+//# sourceMappingURL=self-stage.mjs.map

package/dist/cli/artifacts/self-stage.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"self-stage.mjs","sourceRoot":"","sources":["../../../src/cli/artifacts/self-stage.mjs"],"names":[],"mappings":"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"}

package/dist/cli/bootstrap/detect-mode.d.mts

@@ -0,0 +1,45 @@
+/**
+ * Classify a project as greenfield or brownfield per D-03.
+ *
+ * @param {string} projectDir
+ * @returns {DetectResult}
+ */
+export function detectMode(projectDir: string): DetectResult;
+export type DetectSignals = {
+    /**
+     * Actual count, capped at SCAN_CAP.
+     */
+    sourceFileCount: number;
+    /**
+     * True when we stopped at SCAN_CAP.
+     */
+    sourceCountCapped: boolean;
+    /**
+     * Root-level README.md presence.
+     */
+    hasReadme: boolean;
+    /**
+     * .git directory presence.
+     */
+    hasGit: boolean;
+    /**
+     * 0 when no git or empty history.
+     */
+    commitCount: number;
+};
+export type DetectResult = {
+    mode: "greenfield" | "brownfield";
+    signals: DetectSignals;
+    /**
+     * One bullet per D-03 gate the classifier evaluated.
+     */
+    rationale: string[];
+};
+/** Greenfield threshold for git commit count (D-03). */
+export const GREENFIELD_COMMIT_MAX: 2;
+/** Greenfield threshold for source file count (D-03). */
+export const GREENFIELD_SOURCE_MAX: 10;
+/** Cap scanning at this value — the heuristic only needs to know if we're
+ * above 10, not how far above. Keeps the walk cheap on monorepos. */
+export const SCAN_CAP: 50;
+//# sourceMappingURL=detect-mode.d.mts.map

package/dist/cli/bootstrap/detect-mode.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect-mode.d.mts","sourceRoot":"","sources":["../../../src/cli/bootstrap/detect-mode.mjs"],"names":[],"mappings":"AA+JA;;;;;GAKG;AACH,uCAHW,MAAM,GACJ,YAAY,CAkCxB;;;;;qBA1Ha,MAAM;;;;uBACN,OAAO;;;;eACP,OAAO;;;;YACP,OAAO;;;;iBACP,MAAM;;;UAKN,YAAY,GAAG,YAAY;aAC3B,aAAa;;;;eACb,MAAM,EAAE;;AAhBtB,wDAAwD;AACxD,oCAA8B,CAAC,CAAA;AAJ/B,yDAAyD;AACzD,oCAA8B,EAAE,CAAA;AANhC;qEACqE;AACrE,uBAAiB,EAAE,CAAA"}

package/dist/cli/bootstrap/detect-mode.mjs

@@ -0,0 +1,185 @@
+/**
+ * bootstrap/detect-mode.mjs — greenfield-vs-brownfield heuristic for apt:bootstrap (C47).
+ *
+ * Implements D-03 compound heuristic:
+ *   GREENFIELD ⇔ (source_file_count < 10)  AND
+ *                (no README.md at project root)  AND
+ *                (git commit count ≤ 2 OR no .git)
+ *
+ * Everything else is BROWNFIELD. The tripled-gate design is what makes this
+ * robust — a fresh repo with a stub README stays greenfield UNTIL meaningful
+ * code lands; an existing repo with no README but lots of code is correctly
+ * classified brownfield and will infer rather than interrogate.
+ *
+ * Ties to detect-project.mjs's source-file counter (bounded at 500). We
+ * replicate the extension set + ignore-dirs here so the bootstrap module
+ * stays independent — detect-project.mjs is a CLI command, not a helper
+ * library, and its surface is shaped for a different output envelope.
+ *
+ * No LLM calls. No network. Deterministic, testable.
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, readdirSync } from 'node:fs';
+import { extname, join, resolve } from 'node:path';
+const SOURCE_EXTENSIONS = new Set([
+    '.js',
+    '.mjs',
+    '.cjs',
+    '.ts',
+    '.tsx',
+    '.jsx',
+    '.py',
+    '.rs',
+    '.go',
+    '.java',
+    '.rb',
+    '.vue',
+    '.svelte',
+    '.php',
+    '.cs',
+    '.kt',
+    '.swift',
+]);
+const IGNORE_DIRS = new Set([
+    'node_modules',
+    '.git',
+    '.aperant',
+    'dist',
+    'build',
+    '.next',
+    '.turbo',
+    '.vercel',
+    '.cache',
+    'target',
+    'vendor',
+    '__pycache__',
+    'coverage',
+    'out',
+]);
+/** Cap scanning at this value — the heuristic only needs to know if we're
+ * above 10, not how far above. Keeps the walk cheap on monorepos. */
+const SCAN_CAP = 50;
+const MAX_DEPTH = 5;
+/** Greenfield threshold for source file count (D-03). */
+const GREENFIELD_SOURCE_MAX = 10;
+/** Greenfield threshold for git commit count (D-03). */
+const GREENFIELD_COMMIT_MAX = 2;
+/**
+ * @typedef {Object} DetectSignals
+ * @property {number} sourceFileCount     Actual count, capped at SCAN_CAP.
+ * @property {boolean} sourceCountCapped  True when we stopped at SCAN_CAP.
+ * @property {boolean} hasReadme          Root-level README.md presence.
+ * @property {boolean} hasGit             .git directory presence.
+ * @property {number} commitCount         0 when no git or empty history.
+ */
+/**
+ * @typedef {Object} DetectResult
+ * @property {'greenfield' | 'brownfield'} mode
+ * @property {DetectSignals} signals
+ * @property {string[]} rationale   One bullet per D-03 gate the classifier evaluated.
+ */
+/**
+ * Count source files up to SCAN_CAP in a bounded walk. Returns early once the
+ * cap is hit (a count of 50 is as informative as 500 for the greenfield gate).
+ *
+ * @param {string} rootDir
+ * @returns {{ count: number, capped: boolean }}
+ */
+function countSourceFiles(rootDir) {
+    let count = 0;
+    let capped = false;
+    /** @param {string} dir @param {number} depth */
+    function walk(dir, depth) {
+        if (capped || depth > MAX_DEPTH)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (capped)
+                return;
+            if (e.isDirectory()) {
+                if (IGNORE_DIRS.has(e.name))
+                    continue;
+                // Skip ALL hidden directories (names starting with `.`). This
+                // intentionally excludes .claude/, .cursor/, .github/, .husky/,
+                // .aperant/, etc. — framework and tooling config dirs should not
+                // inflate the source-file count used to classify a project as
+                // brownfield. NOTE: if your project stores significant source files
+                // under a hidden directory (unusual), run apt-tools bootstrap with
+                // --force-brownfield to override the heuristic. (LOG-003)
+                if (e.name.startsWith('.'))
+                    continue;
+                walk(join(dir, e.name), depth + 1);
+            }
+            else if (e.isFile()) {
+                if (SOURCE_EXTENSIONS.has(extname(e.name))) {
+                    count += 1;
+                    if (count >= SCAN_CAP) {
+                        capped = true;
+                        return;
+                    }
+                }
+            }
+        }
+    }
+    walk(rootDir, 0);
+    return { count, capped };
+}
+/**
+ * Best-effort commit count. 0 on any failure — D-03 treats missing git as
+ * "low history" which favors greenfield, matching the intent.
+ *
+ * @param {string} projectDir
+ * @returns {number}
+ */
+function readCommitCount(projectDir) {
+    try {
+        const out = execFileSync('git', ['rev-list', '--count', 'HEAD'], {
+            cwd: projectDir,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        const n = Number.parseInt(out, 10);
+        return Number.isFinite(n) && n >= 0 ? n : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Classify a project as greenfield or brownfield per D-03.
+ *
+ * @param {string} projectDir
+ * @returns {DetectResult}
+ */
+export function detectMode(projectDir) {
+    const resolved = resolve(projectDir);
+    const { count: sourceFileCount, capped: sourceCountCapped } = countSourceFiles(resolved);
+    const hasReadme = existsSync(join(resolved, 'README.md'));
+    const hasGit = existsSync(join(resolved, '.git'));
+    const commitCount = hasGit ? readCommitCount(resolved) : 0;
+    const lowSourceCount = sourceFileCount < GREENFIELD_SOURCE_MAX;
+    const lowCommitGate = !hasGit || commitCount <= GREENFIELD_COMMIT_MAX;
+    const isGreenfield = lowSourceCount && !hasReadme && lowCommitGate;
+    const mode = isGreenfield ? 'greenfield' : 'brownfield';
+    const rationale = [
+        `source_file_count=${sourceFileCount}${sourceCountCapped ? ' (capped)' : ''} ${lowSourceCount ? '< ' : '≥ '}${GREENFIELD_SOURCE_MAX} (greenfield gate)`,
+        `README.md ${hasReadme ? 'present' : 'missing'} (${hasReadme ? 'brownfield' : 'greenfield'} signal)`,
+        hasGit
+            ? `git commit_count=${commitCount} ${commitCount <= GREENFIELD_COMMIT_MAX ? '≤ ' : '> '}${GREENFIELD_COMMIT_MAX} (greenfield gate)`
+            : 'no .git directory (treated as greenfield signal)',
+        `compound → ${mode}`,
+    ];
+    return {
+        mode,
+        signals: { sourceFileCount, sourceCountCapped, hasReadme, hasGit, commitCount },
+        rationale,
+    };
+}
+export { GREENFIELD_COMMIT_MAX, GREENFIELD_SOURCE_MAX, SCAN_CAP };
+//# sourceMappingURL=detect-mode.mjs.map

package/dist/cli/bootstrap/detect-mode.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect-mode.mjs","sourceRoot":"","sources":["../../../src/cli/bootstrap/detect-mode.mjs"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACjD,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AACjD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAElD,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAC;IACjC,KAAK;IACL,MAAM;IACN,MAAM;IACN,KAAK;IACL,MAAM;IACN,MAAM;IACN,KAAK;IACL,KAAK;IACL,KAAK;IACL,OAAO;IACP,KAAK;IACL,MAAM;IACN,SAAS;IACT,MAAM;IACN,KAAK;IACL,KAAK;IACL,QAAQ;CACR,CAAC,CAAA;AAEF,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC;IAC3B,cAAc;IACd,MAAM;IACN,UAAU;IACV,MAAM;IACN,OAAO;IACP,OAAO;IACP,QAAQ;IACR,SAAS;IACT,QAAQ;IACR,QAAQ;IACR,QAAQ;IACR,aAAa;IACb,UAAU;IACV,KAAK;CACL,CAAC,CAAA;AAEF;qEACqE;AACrE,MAAM,QAAQ,GAAG,EAAE,CAAA;AACnB,MAAM,SAAS,GAAG,CAAC,CAAA;AAEnB,yDAAyD;AACzD,MAAM,qBAAqB,GAAG,EAAE,CAAA;AAEhC,wDAAwD;AACxD,MAAM,qBAAqB,GAAG,CAAC,CAAA;AAE/B;;;;;;;GAOG;AAEH;;;;;GAKG;AAEH;;;;;;GAMG;AACH,SAAS,gBAAgB,CAAC,OAAO;IAChC,IAAI,KAAK,GAAG,CAAC,CAAA;IACb,IAAI,MAAM,GAAG,KAAK,CAAA;IAElB,gDAAgD;IAChD,SAAS,IAAI,CAAC,GAAG,EAAE,KAAK;QACvB,IAAI,MAAM,IAAI,KAAK,GAAG,SAAS;YAAE,OAAM;QACvC,IAAI,OAAO,CAAA;QACX,IAAI,CAAC;YACJ,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAA;QACpD,CAAC;QAAC,MAAM,CAAC;YACR,OAAM;QACP,CAAC;QACD,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;YACzB,IAAI,MAAM;gBAAE,OAAM;YAClB,IAAI,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;gBACrB,IAAI,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;oBAAE,SAAQ;gBACrC,8DAA8D;gBAC9D,gEAAgE;gBAChE,iEAAiE;gBACjE,8DAA8D;gBAC9D,oEAAoE;gBACpE,mEAAmE;gBACnE,0DAA0D;gBAC1D,IAAI,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;oBAAE,SAAQ;gBACpC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,CAAA;YACnC,CAAC;iBAAM,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC;gBACvB,IAAI,iBAAiB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;oBAC5C,KAAK,IAAI,CAAC,CAAA;oBACV,IAAI,KAAK,IAAI,QAAQ,EAAE,CAAC;wBACvB,MAAM,GAAG,IAAI,CAAA;wBACb,OAAM;oBACP,CAAC;gBACF,CAAC;YACF,CAAC;QACF,CAAC;IACF,CAAC;IAED,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAA;IAChB,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,CAAA;AACzB,CAAC;AAED;;;;;;GAMG;AACH,SAAS,eAAe,CAAC,UAAU;IAClC,IAAI,CAAC;QACJ,MAAM,GAAG,GAAG,YAAY,CAAC,KAAK,EAAE,CAAC,UAAU,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE;YAChE,GAAG,EAAE,UAAU;YACf,QAAQ,EAAE,OAAO;YACjB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC;SACnC,CAAC,CAAC,IAAI,EAAE,CAAA;QACT,MAAM,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAA;QAClC,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IAC5C,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,CAAC,CAAA;IACT,CAAC;AACF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,UAAU;IACpC,MAAM,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;IAEpC,MAAM,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,iBAAiB,EAAE,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAAA;IACxF,MAAM,SAAS,GAAG,UAAU,CAAC,IAAI,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC,CAAA;IACzD,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAA;IACjD,MAAM,WAAW,GAAG,MAAM,CAAC,CAAC,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IAE1D,MAAM,cAAc,GAAG,eAAe,GAAG,qBAAqB,CAAA;IAC9D,MAAM,aAAa,GAAG,CAAC,MAAM,IAAI,WAAW,IAAI,qBAAqB,CAAA;IAErE,MAAM,YAAY,GAAG,cAAc,IAAI,CAAC,SAAS,IAAI,aAAa,CAAA;IAClE,MAAM,IAAI,GAAG,YAAY,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,YAAY,CAAA;IAEvD,MAAM,SAAS,GAAG;QACjB,qBAAqB,eAAe,GAAG,iBAAiB,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,IAC1E,cAAc,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IACzB,GAAG,qBAAqB,oBAAoB;QAC5C,aAAa,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,YAAY,UAAU;QACpG,MAAM;YACL,CAAC,CAAC,oBAAoB,WAAW,IAC/B,WAAW,IAAI,qBAAqB,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAC/C,GAAG,qBAAqB,oBAAoB;YAC7C,CAAC,CAAC,kDAAkD;QACrD,cAAc,IAAI,EAAE;KACpB,CAAA;IAED,OAAO;QACN,IAAI;QACJ,OAAO,EAAE,EAAE,eAAe,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE;QAC/E,SAAS;KACT,CAAA;AACF,CAAC;AAED,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,QAAQ,EAAE,CAAA"}

package/dist/cli/bootstrap/product-context-sidecar.d.mts

@@ -0,0 +1,94 @@
+/**
+ * Derive product-context.json fields from a parsed PROJECT.md. Returns the
+ * full sidecar envelope ready for `atomicWriteJson`.
+ *
+ * @param {string} markdown
+ * @param {{ packageName?: string | null, packageDescription?: string | null, now?: string } | undefined} opts
+ * @returns {SidecarResult}
+ */
+export function deriveSidecar(markdown: string, opts?: {
+    packageName?: string | null;
+    packageDescription?: string | null;
+    now?: string;
+} | undefined): SidecarResult;
+/**
+ * bootstrap/product-context-sidecar.mjs — PROJECT.md → product-context.json
+ * derivation for apt:bootstrap (D-01).
+ *
+ * PROJECT.md is the single source of truth (prose). product-context.json is a
+ * DERIVED sidecar, regenerated from PROJECT.md on every write. The flow is
+ * strictly one-way here — this module never reads product-context.json and
+ * never edits PROJECT.md.
+ *
+ * The parser is shape-aware, not prose-aware: it splits on PROJECT.md's
+ * D-06 fixed headings and captures the body of each section as free-form
+ * text. The only structured extraction is the Features sub-list under "Scope"
+ * (when present) — PROJECT.md may list in/out scope items as bullets, and
+ * we split those into scopeIn[] / scopeOut[] arrays so downstream consumers
+ * (C49 apt:create-docs) can iterate them directly.
+ *
+ * Confidence markers (D-09) — HTML comments of the form
+ *   `<!-- confidence: medium | evidence: README.md:1-20 -->`
+ * — are stripped from the prose bodies but preserved on a per-section
+ * basis inside the sidecar's `_confidence` block, so downstream tooling
+ * can reason about freshness without re-parsing the markdown.
+ *
+ * Output shape is additive-compatible with
+ * packages/framework/templates/product-context.schema.json (C44) — every
+ * required key is present. Optional enrichments (scopeIn/scopeOut/context/
+ * constraints/keyDecisions/personasRef/_confidence) are additive and pass
+ * the schema's `additionalProperties: true` on the root.
+ *
+ * No LLM calls. Deterministic, testable.
+ */
+/** The seven canonical sections (D-06). Ordered. */
+export const CANONICAL_SECTIONS: string[];
+export type ConfidenceMarker = {
+    /**
+     * (normalized lowercase; unknown passes through)
+     */
+    level: "high" | "medium" | "low" | string;
+    evidence: string | null;
+};
+export type ParsedSection = {
+    /**
+     * Canonical title from CANONICAL_SECTIONS.
+     */
+    title: string;
+    /**
+     * Prose with HTML comments stripped.
+     */
+    body: string;
+    /**
+     * First confidence comment found in the section.
+     */
+    confidence: ConfidenceMarker | null;
+};
+export type SidecarResult = {
+    productName: string;
+    productDescription: string;
+    targetAudience: string;
+    features: Array<{
+        id: string;
+        name: string;
+        description?: string;
+    }>;
+    scopeIn: string[];
+    scopeOut: string[];
+    context: string;
+    constraints: string[];
+    keyDecisions: string[];
+    /**
+     * e.g., ".aperant/personas.json"
+     */
+    personasRef: string | null;
+    /**
+     * keyed by section title slug
+     */
+    _confidence: Record<string, ConfidenceMarker>;
+    _meta: {
+        source: "PROJECT.md";
+        updatedAt: string;
+    };
+};
+//# sourceMappingURL=product-context-sidecar.d.mts.map

package/dist/cli/bootstrap/product-context-sidecar.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"product-context-sidecar.d.mts","sourceRoot":"","sources":["../../../src/cli/bootstrap/product-context-sidecar.mjs"],"names":[],"mappings":"AA+QA;;;;;;;GAOG;AACH,wCAJW,MAAM,SACN;IAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,GAC3F,aAAa,CAuGzB;AA5XD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,oDAAoD;AACpD,0CAQC;;;;;WAaa,MAAM,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM;cAClC,MAAM,GAAG,IAAI;;;;;;WAKb,MAAM;;;;UACN,MAAM;;;;gBACN,gBAAgB,GAAG,IAAI;;;iBAKvB,MAAM;wBACN,MAAM;oBACN,MAAM;cACN,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;aACzD,MAAM,EAAE;cACR,MAAM,EAAE;aACR,MAAM;iBACN,MAAM,EAAE;kBACR,MAAM,EAAE;;;;iBACR,MAAM,GAAG,IAAI;;;;iBACb,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC;WAChC;QAAE,MAAM,EAAE,YAAY,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE"}