@aperant/framework 0.6.2

package/dist/cli/bootstrap/product-context-sidecar.mjs

@@ -0,0 +1,367 @@
+/**
+ * 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 = [
+    'What This Is',
+    'Core Value',
+    'Scope',
+    'Context',
+    'Personas',
+    'Constraints',
+    'Key Decisions',
+];
+const CONFIDENCE_COMMENT_RE = /<!--\s*confidence:\s*([^|]+?)\s*(?:\|\s*evidence:\s*([^>]+?)\s*)?-->/i;
+const HTML_COMMENT_RE = /<!--[\s\S]*?-->/g;
+// Separator class is `[:—]` (colon + em-dash only) — do NOT include plain
+// ASCII `-` here. A trailing `-` in the class would eagerly consume the
+// newline + next bullet's leading `-`, dropping the first scope item.
+const IN_SCOPE_RE = /^#{2,4}[ \t]*In(?:[ \t]*[:—]|[ \t]*$)/im;
+const OUT_SCOPE_RE = /^#{2,4}[ \t]*Out(?:[ \t]*[:—]|[ \t]*$)/im;
+/**
+ * @typedef {Object} ConfidenceMarker
+ * @property {'high' | 'medium' | 'low' | string} level   (normalized lowercase; unknown passes through)
+ * @property {string | null} evidence
+ */
+/**
+ * @typedef {Object} ParsedSection
+ * @property {string} title     Canonical title from CANONICAL_SECTIONS.
+ * @property {string} body      Prose with HTML comments stripped.
+ * @property {ConfidenceMarker | null} confidence   First confidence comment found in the section.
+ */
+/**
+ * @typedef {Object} SidecarResult
+ * @property {string} productName
+ * @property {string} productDescription
+ * @property {string} targetAudience
+ * @property {Array<{ id: string, name: string, description?: string }>} features
+ * @property {string[]} scopeIn
+ * @property {string[]} scopeOut
+ * @property {string} context
+ * @property {string[]} constraints
+ * @property {string[]} keyDecisions
+ * @property {string | null} personasRef   e.g., ".aperant/personas.json"
+ * @property {Record<string, ConfidenceMarker>} _confidence  keyed by section title slug
+ * @property {{ source: 'PROJECT.md', updatedAt: string }} _meta
+ */
+/**
+ * Extract the title text and body of every ## section in a PROJECT.md body.
+ * Only titles that case-insensitively match a CANONICAL_SECTIONS entry are
+ * retained — stray sections are dropped (D-06's kill criteria speaks to
+ * future custom-section allowlisting; today we just ignore them).
+ *
+ * @param {string} markdown
+ * @returns {ParsedSection[]}
+ */
+function splitSections(markdown) {
+    const lines = markdown.split(/\r?\n/);
+    /** @type {ParsedSection[]} */
+    const sections = [];
+    let current = null;
+    /** Push the in-flight section if it matches a canonical title. */
+    const flush = () => {
+        if (!current)
+            return;
+        const canonical = matchCanonical(current.rawTitle);
+        if (canonical !== null) {
+            const rawBody = current.bodyLines.join('\n').trim();
+            const confidence = extractConfidence(rawBody);
+            const cleanBody = rawBody
+                .replace(HTML_COMMENT_RE, '')
+                .replace(/\n{3,}/g, '\n\n')
+                .trim();
+            sections.push({ title: canonical, body: cleanBody, confidence });
+        }
+    };
+    for (const line of lines) {
+        const m = /^##\s+(.+?)\s*$/.exec(line);
+        if (m) {
+            flush();
+            current = { rawTitle: m[1], bodyLines: [] };
+            continue;
+        }
+        if (current) {
+            current.bodyLines.push(line);
+        }
+    }
+    flush();
+    return sections;
+}
+/**
+ * @param {string} raw
+ * @returns {string | null}
+ */
+function matchCanonical(raw) {
+    const norm = raw.trim().toLowerCase();
+    for (const title of CANONICAL_SECTIONS) {
+        const canonNorm = title.toLowerCase();
+        if (norm === canonNorm)
+            return title;
+        // Allow "Scope (In/Out)" variants to match "Scope".
+        if (title === 'Scope' && norm.startsWith('scope'))
+            return 'Scope';
+    }
+    return null;
+}
+/**
+ * @param {string} body
+ * @returns {ConfidenceMarker | null}
+ */
+function extractConfidence(body) {
+    const m = CONFIDENCE_COMMENT_RE.exec(body);
+    if (!m)
+        return null;
+    const level = m[1].trim().toLowerCase();
+    const evidence = m[2] ? m[2].trim() : null;
+    return { level, evidence };
+}
+/**
+ * @param {string} title
+ * @returns {string}
+ */
+function slugifyTitle(title) {
+    return title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '_')
+        .replace(/^_|_$/g, '');
+}
+/**
+ * Pull markdown bullets out of a section body. Matches `- `, `* `, and
+ * numbered `1. ` styles. Blank lines end a list; nested items are flattened.
+ *
+ * @param {string} body
+ * @returns {string[]}
+ */
+function extractBullets(body) {
+    /** @type {string[]} */
+    const bullets = [];
+    for (const raw of body.split(/\r?\n/)) {
+        const m = /^\s*(?:[-*]|\d+\.)\s+(.+?)\s*$/.exec(raw);
+        if (m) {
+            const text = m[1].trim();
+            if (text.length > 0)
+                bullets.push(text);
+        }
+    }
+    return bullets;
+}
+/**
+ * Split a Scope section into scopeIn / scopeOut arrays. The template admits
+ * either a single bullet list with `In:` / `Out:` prefixes or two sub-headings
+ * (### In / ### Out). This handler covers both.
+ *
+ * @param {string} body
+ * @returns {{ scopeIn: string[], scopeOut: string[] }}
+ */
+function splitScope(body) {
+    const inMatch = body.match(IN_SCOPE_RE);
+    const outMatch = body.match(OUT_SCOPE_RE);
+    if (inMatch && outMatch) {
+        const inIdx = inMatch.index ?? 0;
+        const outIdx = outMatch.index ?? 0;
+        let inBody = '';
+        let outBody = '';
+        if (inIdx < outIdx) {
+            inBody = body.slice(inIdx + inMatch[0].length, outIdx);
+            outBody = body.slice(outIdx + outMatch[0].length);
+        }
+        else {
+            outBody = body.slice(outIdx + outMatch[0].length, inIdx);
+            inBody = body.slice(inIdx + inMatch[0].length);
+        }
+        return { scopeIn: extractBullets(inBody), scopeOut: extractBullets(outBody) };
+    }
+    // Flat list with inline prefix ("- In: foo" / "- Out: bar").
+    /** @type {string[]} */
+    const scopeIn = [];
+    /** @type {string[]} */
+    const scopeOut = [];
+    for (const bullet of extractBullets(body)) {
+        const inPrefix = /^in\s*[:—-]\s*(.+)$/i.exec(bullet);
+        const outPrefix = /^out\s*[:—-]\s*(.+)$/i.exec(bullet);
+        if (inPrefix)
+            scopeIn.push(inPrefix[1].trim());
+        else if (outPrefix)
+            scopeOut.push(outPrefix[1].trim());
+        else
+            scopeIn.push(bullet);
+    }
+    return { scopeIn, scopeOut };
+}
+/**
+ * Derive a stable feature id from a human-facing name.
+ *
+ * @param {string} name
+ * @param {Set<string>} used   Already-emitted ids to de-duplicate.
+ * @returns {string}
+ */
+function featureIdFrom(name, used) {
+    const base = name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '')
+        .slice(0, 40) || 'feature';
+    let id = base;
+    let i = 2;
+    while (used.has(id)) {
+        id = `${base}-${i}`;
+        i += 1;
+    }
+    used.add(id);
+    return id;
+}
+/**
+ * Pull a one-line "product name" out of the "What This Is" section. Prefers
+ * a leading bold line or a bare first line; falls back to a supplied
+ * packageName when PROJECT.md has only prose.
+ *
+ * @param {string} whatThisIs
+ * @param {string | null} packageName
+ */
+function inferProductName(whatThisIs, packageName) {
+    if (!whatThisIs)
+        return packageName || 'Unnamed Project';
+    // Leading bold line: **Name** — rest of description.
+    const bold = /^\*\*([^*]+)\*\*/.exec(whatThisIs);
+    if (bold)
+        return bold[1].trim();
+    // Leading "Name: description" pattern.
+    const colon = /^([^:\n]{1,80}):/.exec(whatThisIs);
+    if (colon)
+        return colon[1].trim();
+    // Fall back to first line.
+    const firstLine = whatThisIs.split(/\r?\n/)[0].trim();
+    if (firstLine.length > 0 && firstLine.length <= 80)
+        return firstLine;
+    return packageName || 'Unnamed Project';
+}
+/**
+ * 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, opts = {}) {
+    const sections = splitSections(markdown);
+    /** @type {Record<string, ParsedSection>} */
+    const byTitle = {};
+    for (const s of sections)
+        byTitle[s.title] = s;
+    // Warn on stderr for any canonical section that is absent from the parsed
+    // PROJECT.md. Missing sections produce empty fields downstream — silently
+    // receiving empty strings for productDescription, context, etc. makes it
+    // hard for callers to distinguish a blank section from a missing one. We
+    // do NOT fail here; the sidecar is still written with empty-string defaults
+    // (the schema allows it), but callers and operators deserve to know. (QUA-007)
+    const missingSections = CANONICAL_SECTIONS.filter((t) => !(t in byTitle));
+    if (missingSections.length > 0) {
+        process.stderr.write(`[bootstrap/derive-sidecar] WARN: PROJECT.md is missing ${missingSections.length} canonical section(s): ${missingSections.join(', ')}. Corresponding sidecar fields will be empty.\n`);
+    }
+    const whatThisIsBody = byTitle['What This Is']?.body ?? '';
+    const coreValueBody = byTitle['Core Value']?.body ?? '';
+    const scopeBody = byTitle['Scope']?.body ?? '';
+    const contextBody = byTitle['Context']?.body ?? '';
+    const personasBody = byTitle['Personas']?.body ?? '';
+    const constraintsBody = byTitle['Constraints']?.body ?? '';
+    const keyDecisionsBody = byTitle['Key Decisions']?.body ?? '';
+    const productName = inferProductName(whatThisIsBody, opts.packageName ?? null);
+    const productDescription = coreValueBody.trim() || whatThisIsBody.trim() || opts.packageDescription?.trim() || '';
+    // Target audience — heuristic: first non-empty line of Personas that looks
+    // like prose (not a ref link). If Personas is empty, fall back to the
+    // Context section first paragraph.
+    let targetAudience = '';
+    for (const line of personasBody.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        if (trimmed.startsWith('See ') || trimmed.startsWith('Reference:'))
+            continue;
+        targetAudience = trimmed;
+        break;
+    }
+    if (!targetAudience) {
+        const firstPara = contextBody.split(/\n\s*\n/)[0]?.trim() ?? '';
+        targetAudience = firstPara;
+    }
+    // Features — the template doesn't carry a Features section; pull bullets
+    // from scopeIn as the closest canonical "things this product does". If
+    // there's no Scope, emit an empty array (schema allows it).
+    const { scopeIn, scopeOut } = splitScope(scopeBody);
+    const usedIds = new Set();
+    const features = scopeIn.map((item) => {
+        const name = item.replace(/\s*[—-]\s*.+$/, '').trim() || item;
+        const description = item.includes('—')
+            ? item.split('—', 2)[1].trim()
+            : item.includes(' - ')
+                ? item.split(' - ', 2)[1].trim()
+                : '';
+        return {
+            id: featureIdFrom(name, usedIds),
+            name,
+            ...(description ? { description } : {}),
+        };
+    });
+    // Personas reference — look for a `.aperant/personas.json` mention or
+    // default to the standard path if the section is non-empty.
+    let personasRef = null;
+    const personasRefMatch = /(\.aperant\/personas\.json)/.exec(personasBody);
+    if (personasRefMatch) {
+        personasRef = personasRefMatch[1];
+    }
+    else if (personasBody.trim().length > 0) {
+        personasRef = '.aperant/personas.json';
+    }
+    const constraints = extractBullets(constraintsBody);
+    const keyDecisions = extractBullets(keyDecisionsBody);
+    /** @type {Record<string, ConfidenceMarker>} */
+    const confidence = {};
+    for (const s of sections) {
+        if (s.confidence)
+            confidence[slugifyTitle(s.title)] = s.confidence;
+    }
+    const now = opts.now ?? new Date().toISOString();
+    return {
+        productName,
+        productDescription,
+        targetAudience,
+        features,
+        scopeIn,
+        scopeOut,
+        context: contextBody,
+        constraints,
+        keyDecisions,
+        personasRef,
+        _confidence: confidence,
+        _meta: { source: 'PROJECT.md', updatedAt: now },
+    };
+}
+//# sourceMappingURL=product-context-sidecar.mjs.map

package/dist/cli/bootstrap/product-context-sidecar.mjs.map

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

package/dist/cli/bootstrap/recon.d.mts

@@ -0,0 +1,52 @@
+/**
+ * Run the deterministic recon pass. Safe to call on any directory — missing
+ * files produce `present: false` markers rather than throwing.
+ *
+ * @param {string} projectDir
+ * @returns {ReconResult}
+ */
+export function runRecon(projectDir: string): ReconResult;
+export type ReconPackageJson = {
+    name: string | null;
+    description: string | null;
+    keywords: string[];
+    /**
+     * Normalized URL (.url if object form) or raw string.
+     */
+    repository: string | null;
+};
+export type ReconMarkdown = {
+    path: string;
+    present: boolean;
+    body: string | null;
+    truncated: boolean;
+};
+export type ReconResult = {
+    /**
+     * Absolute resolved path.
+     */
+    projectDir: string;
+    readme: ReconMarkdown;
+    claudeMd: ReconMarkdown;
+    agentsMd: ReconMarkdown;
+    packageJson: {
+        path: string;
+        present: boolean;
+        data: ReconPackageJson | null;
+    };
+    topLevelFolders: string[];
+    /**
+     * origin URL if available.
+     */
+    gitRemoteUrl: string | null;
+    /**
+     * Subject of the oldest commit, or null.
+     */
+    firstCommitMessage: string | null;
+    /**
+     * Any non-fatal diagnostics (e.g., "git missing").
+     */
+    notes: string[];
+};
+export const READ_CAP_BYTES: number;
+//# sourceMappingURL=recon.d.mts.map

package/dist/cli/bootstrap/recon.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recon.d.mts","sourceRoot":"","sources":["../../../src/cli/bootstrap/recon.mjs"],"names":[],"mappings":"AAuNA;;;;;;GAMG;AACH,qCAHW,MAAM,GACJ,WAAW,CAoCvB;;UAlNa,MAAM,GAAG,IAAI;iBACb,MAAM,GAAG,IAAI;cACb,MAAM,EAAE;;;;gBACR,MAAM,GAAG,IAAI;;;UAKb,MAAM;aACN,OAAO;UACP,MAAM,GAAG,IAAI;eACb,OAAO;;;;;;gBAKP,MAAM;YACN,aAAa;cACb,aAAa;cACb,aAAa;iBACb;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,gBAAgB,GAAG,IAAI,CAAA;KAAE;qBACjE,MAAM,EAAE;;;;kBACR,MAAM,GAAG,IAAI;;;;wBACb,MAAM,GAAG,IAAI;;;;WACb,MAAM,EAAE;;AA5CtB,oCAA+B"}

package/dist/cli/bootstrap/recon.mjs

@@ -0,0 +1,248 @@
+/**
+ * bootstrap/recon.mjs — deterministic repo recon for apt:bootstrap (C47).
+ *
+ * Reads a FIXED allowlist (D-02) of well-known repo-root signals and returns a
+ * structured object. No LLM calls, no network, no filesystem discovery beyond
+ * the allowlist. Graceful on missing files — each field is independently
+ * nullable so the SKILL.md body can feed whatever is present into the LLM.
+ *
+ * Allowlist (D-02):
+ *   - README.md (first 8KB)
+ *   - CLAUDE.md (first 8KB)
+ *   - AGENTS.md (first 8KB)
+ *   - package.json — ONLY description / keywords / repository / name
+ *   - top-level folder names, one level deep (skip hidden + ignored)
+ *   - git remote url (origin)
+ *   - first commit message (oldest)
+ *
+ * The "first 8KB" cap on markdown reads is intentional — recon is a signal
+ * extractor, not a documentation parser. Anything past 8KB of prose rarely
+ * adds inference signal and growing the byte cap trades latency for noise.
+ */
+import { execFileSync } from 'node:child_process';
+import { closeSync, existsSync, openSync, readdirSync, readFileSync, readSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+const READ_CAP_BYTES = 8 * 1024;
+const IGNORE_DIRS = new Set([
+    'node_modules',
+    '.git',
+    '.aperant',
+    'dist',
+    'build',
+    '.next',
+    '.turbo',
+    '.vercel',
+    '.cache',
+    'target',
+    'vendor',
+    '__pycache__',
+    'coverage',
+]);
+/**
+ * @typedef {Object} ReconPackageJson
+ * @property {string | null} name
+ * @property {string | null} description
+ * @property {string[]} keywords
+ * @property {string | null} repository  Normalized URL (.url if object form) or raw string.
+ */
+/**
+ * @typedef {Object} ReconMarkdown
+ * @property {string} path
+ * @property {boolean} present
+ * @property {string | null} body
+ * @property {boolean} truncated
+ */
+/**
+ * @typedef {Object} ReconResult
+ * @property {string} projectDir              Absolute resolved path.
+ * @property {ReconMarkdown} readme
+ * @property {ReconMarkdown} claudeMd
+ * @property {ReconMarkdown} agentsMd
+ * @property {{ path: string, present: boolean, data: ReconPackageJson | null }} packageJson
+ * @property {string[]} topLevelFolders
+ * @property {string | null} gitRemoteUrl     origin URL if available.
+ * @property {string | null} firstCommitMessage  Subject of the oldest commit, or null.
+ * @property {string[]} notes                 Any non-fatal diagnostics (e.g., "git missing").
+ */
+/**
+ * Read a text file capped at READ_CAP_BYTES. Returns { body, truncated } or
+ * null on any failure. We use openSync + readSync (not readFileSync with a
+ * buffer slice) so we can correctly flag truncation — a file might be shorter
+ * than the cap, longer, or exactly the cap.
+ *
+ * @param {string} path
+ * @returns {{ body: string, truncated: boolean } | null}
+ */
+function readCapped(path) {
+    let fd = null;
+    try {
+        fd = openSync(path, 'r');
+        const buf = Buffer.alloc(READ_CAP_BYTES + 1);
+        const bytesRead = readSync(fd, buf, 0, buf.length, 0);
+        const truncated = bytesRead > READ_CAP_BYTES;
+        const slice = buf.subarray(0, Math.min(bytesRead, READ_CAP_BYTES));
+        return { body: slice.toString('utf-8'), truncated };
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (fd !== null) {
+            try {
+                closeSync(fd);
+            }
+            catch {
+                /* best-effort */
+            }
+        }
+    }
+}
+/**
+ * Shape a capped-read result into the recon envelope's markdown shape.
+ *
+ * @param {string} path
+ */
+function readMarkdown(path) {
+    if (!existsSync(path)) {
+        return { path, present: false, body: null, truncated: false };
+    }
+    const res = readCapped(path);
+    if (res === null) {
+        return { path, present: true, body: null, truncated: false };
+    }
+    return { path, present: true, body: res.body, truncated: res.truncated };
+}
+/**
+ * Extract the D-02-allowlisted fields from package.json. Tolerant of either
+ * the string or object form of `repository`. Unknown keys are ignored.
+ *
+ * @param {string} path
+ * @returns {ReconPackageJson | null}
+ */
+function readPackageJson(path) {
+    if (!existsSync(path))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return null;
+    }
+    let repository = null;
+    if (typeof parsed.repository === 'string') {
+        repository = parsed.repository;
+    }
+    else if (parsed.repository !== null &&
+        typeof parsed.repository === 'object' &&
+        typeof parsed.repository.url === 'string') {
+        repository = parsed.repository.url;
+    }
+    return {
+        name: typeof parsed.name === 'string' ? parsed.name : null,
+        description: typeof parsed.description === 'string' ? parsed.description : null,
+        keywords: Array.isArray(parsed.keywords)
+            ? parsed.keywords.filter((k) => typeof k === 'string')
+            : [],
+        repository,
+    };
+}
+/**
+ * List top-level directories in `projectDir`, skipping hidden + ignored. One
+ * level deep — D-02 explicitly forbids recursive discovery here.
+ *
+ * @param {string} projectDir
+ * @returns {string[]}
+ */
+function listTopLevelFolders(projectDir) {
+    try {
+        return readdirSync(projectDir, { withFileTypes: true })
+            .filter((e) => e.isDirectory() && !e.name.startsWith('.') && !IGNORE_DIRS.has(e.name))
+            .map((e) => e.name)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Best-effort git remote URL. Prefers `origin`; returns null on any failure.
+ *
+ * @param {string} projectDir
+ * @returns {string | null}
+ */
+function readGitRemoteUrl(projectDir) {
+    try {
+        const url = execFileSync('git', ['config', '--get', 'remote.origin.url'], {
+            cwd: projectDir,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        return url.length > 0 ? url : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Best-effort first (oldest) commit subject. Returns null on any failure,
+ * including repos with zero commits.
+ *
+ * @param {string} projectDir
+ * @returns {string | null}
+ */
+function readFirstCommitMessage(projectDir) {
+    try {
+        const subject = execFileSync('git', ['log', '--reverse', '--format=%s', '-1'], {
+            cwd: projectDir,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        return subject.length > 0 ? subject : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Run the deterministic recon pass. Safe to call on any directory — missing
+ * files produce `present: false` markers rather than throwing.
+ *
+ * @param {string} projectDir
+ * @returns {ReconResult}
+ */
+export function runRecon(projectDir) {
+    const resolved = resolve(projectDir);
+    const notes = [];
+    const readme = readMarkdown(join(resolved, 'README.md'));
+    const claudeMd = readMarkdown(join(resolved, 'CLAUDE.md'));
+    const agentsMd = readMarkdown(join(resolved, 'AGENTS.md'));
+    const pkgPath = join(resolved, 'package.json');
+    const packageJson = {
+        path: pkgPath,
+        present: existsSync(pkgPath),
+        data: readPackageJson(pkgPath),
+    };
+    const topLevelFolders = listTopLevelFolders(resolved);
+    const gitRemoteUrl = readGitRemoteUrl(resolved);
+    const firstCommitMessage = readFirstCommitMessage(resolved);
+    if (!existsSync(join(resolved, '.git'))) {
+        notes.push('no .git directory — git-derived signals skipped');
+    }
+    return {
+        projectDir: resolved,
+        readme,
+        claudeMd,
+        agentsMd,
+        packageJson,
+        topLevelFolders,
+        gitRemoteUrl,
+        firstCommitMessage,
+        notes,
+    };
+}
+export { READ_CAP_BYTES };
+//# sourceMappingURL=recon.mjs.map