@ramplab/generator 0.1.0

package/dist/authorStage.js

@@ -0,0 +1,284 @@
+import { z } from 'zod';
+import { moduleSchema } from '@ramplab/spec';
+import { extractJson } from './mapStage.js';
+import { mapWithConcurrency } from './pipeline.js';
+/**
+ * The author stage (PLAN.md §4, pass 2): fan out one authoring agent per
+ * planned module, in parallel under a small concurrency cap. Each agent
+ * writes a full module — a mix of anchored widgets (callouts, code
+ * walkthroughs, code figures, diagrams, and a closing quiz) — validated
+ * against `@ramplab/spec`'s module schema with the same bounded retry the
+ * other stages use.
+ *
+ * Diagrams are budgeted, not left over (founder, 2026-07-25): the Edition v2
+ * threads gave every module several prose obligations inside an unchanged
+ * 4-to-8 widget budget, and the only widget family described as optional —
+ * the diagrams — is what got squeezed out. Live editions pressed on 2026-07-13
+ * carried 3-5 system maps; those pressed on 2026-07-14 carried 1-2, with the
+ * callout share climbing from 29% to 50% across the same five editions. The
+ * range now starts higher, the diagram catalogue sits above code-figure and
+ * quiz rather than last, and {@link SHAPE_CONTRACT} states the expectation
+ * outright. The escape hatch stays honest: no diagram where the code has no
+ * shape, and every node still carries its own anchor.
+ *
+ * Narrative continuity without serializing the fan-out (issue #18): each
+ * author prompt carries its module's **learner-state ledger slice** — what
+ * the learner has already seen (`assumes`, plus the titles of earlier
+ * modules it may reference), and what this module must add (`teaches`) —
+ * plus the **style contract** (concrete before abstract, jargon defined at
+ * first use, analogies anchored, mechanism-and-why over structural survey).
+ *
+ * Failure policy (deliberate, documented): a module that is still
+ * schema-invalid after its retries **fails the whole stage** with an error
+ * naming the module — there is no silent-skip mode. A planned module is a
+ * curriculum commitment; dropping it quietly would ship a lab with a hole
+ * the lead never sees. Other in-flight modules finish before the error is
+ * raised, so all failures are reported at once.
+ */
+/** Default cap on concurrent authoring agents. */
+export const DEFAULT_AUTHOR_CONCURRENCY = 4;
+/**
+ * Widgets per authored chapter. The floor clears the module's mandatory prose
+ * — a quiz, the capability callout, the "when it breaks" warning, the threads
+ * the plan assigned — so a diagram has somewhere to go.
+ */
+export const DEFAULT_WIDGET_RANGE = { min: 6, max: 10 };
+/** Widgets per chapter for repos deep enough to earn a 7-module plan. */
+export const DEEP_WIDGET_RANGE = { min: 7, max: 12 };
+/** Raised when at least one planned module never produced a valid module. */
+export class AuthorStageError extends Error {
+    failures;
+    constructor(failures) {
+        const detail = failures
+            .map((f) => `- module "${f.moduleId}" failed after ${f.attempts} attempt` +
+            `${f.attempts === 1 ? '' : 's'}:\n${indent(f.lastFailure)}`)
+            .join('\n');
+        super(`Author stage failed: ${failures.length} planned module` +
+            `${failures.length === 1 ? '' : 's'} did not produce valid output.\n${detail}`);
+        this.name = 'AuthorStageError';
+        this.failures = failures;
+    }
+}
+function indent(text) {
+    return text
+        .split('\n')
+        .map((line) => `    ${line}`)
+        .join('\n');
+}
+export async function runAuthorStage(runner, repoDir, options) {
+    const concurrency = Math.max(1, options.concurrency ?? DEFAULT_AUTHOR_CONCURRENCY);
+    const planned = options.plan.modules;
+    // Each module's ledger slice includes the titles of the modules before it —
+    // any chapters preceding this plan entirely, then the plan's own earlier
+    // modules — the names an author may reference for continuity.
+    const preceding = options.precedingTitles ?? [];
+    const entries = planned.map((module, index) => ({
+        module,
+        earlierTitles: [...preceding, ...planned.slice(0, index).map((earlier) => earlier.title)],
+    }));
+    const outcomes = await mapWithConcurrency(entries, concurrency, (entry) => authorModule(runner, repoDir, entry.module, entry.earlierTitles, options));
+    let costUsd;
+    const modules = [];
+    const failures = [];
+    for (const outcome of outcomes) {
+        if (outcome.costUsd !== undefined) {
+            costUsd = (costUsd ?? 0) + outcome.costUsd;
+        }
+        if (outcome.ok) {
+            modules.push({ module: outcome.module, attempts: outcome.attempts });
+        }
+        else {
+            failures.push(outcome.failure);
+        }
+    }
+    if (failures.length > 0) {
+        throw new AuthorStageError(failures);
+    }
+    return { modules, costUsd };
+}
+async function authorModule(runner, repoDir, planned, earlierTitles, options) {
+    const maxRetries = options.maxRetries ?? 1;
+    const maxAttempts = 1 + Math.max(0, maxRetries);
+    const range = options.widgetRange ?? DEFAULT_WIDGET_RANGE;
+    const basePrompt = buildAuthorPrompt(planned, earlierTitles, range);
+    let costUsd;
+    let lastFailure = 'no attempt was made';
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        const prompt = attempt === 1 ? basePrompt : `${basePrompt}\n\n${retryPreamble(lastFailure)}`;
+        const response = await runner.runStage({
+            stage: 'author',
+            model: options.model,
+            repoDir,
+            prompt,
+            attempt,
+        });
+        if (response.costUsd !== undefined) {
+            costUsd = (costUsd ?? 0) + response.costUsd;
+        }
+        const outcome = assembleModule(response.output, planned);
+        if (outcome.ok) {
+            options.onModuleAuthored?.({ module: outcome.module, attempts: attempt });
+            return { ok: true, module: outcome.module, attempts: attempt, costUsd };
+        }
+        lastFailure = outcome.failure;
+    }
+    return {
+        ok: false,
+        failure: { moduleId: planned.id, attempts: maxAttempts, lastFailure },
+        costUsd,
+    };
+}
+/**
+ * Parse the model's text as the author payload and assemble the module
+ * around the plan's stable id/title. Validation is a single path: the
+ * assembled module must pass `@ramplab/spec`'s module schema, plus a
+ * non-empty-widgets floor (an empty module teaches nothing).
+ */
+function assembleModule(output, planned) {
+    const json = extractJson(output);
+    if (json === undefined) {
+        return { ok: false, failure: 'The output did not contain a parseable JSON object.' };
+    }
+    if (typeof json !== 'object' || json === null || Array.isArray(json)) {
+        return { ok: false, failure: 'The output JSON must be an object.' };
+    }
+    const payload = json;
+    const candidate = {
+        id: planned.id,
+        title: planned.title,
+        ...(typeof payload['summary'] === 'string' && payload['summary'].length > 0
+            ? { summary: payload['summary'] }
+            : {}),
+        widgets: payload['widgets'],
+    };
+    const parsed = moduleSchema.safeParse(candidate);
+    if (!parsed.success) {
+        return { ok: false, failure: z.prettifyError(parsed.error) };
+    }
+    if (parsed.data.widgets.length === 0) {
+        return { ok: false, failure: 'The module must contain at least one widget.' };
+    }
+    return { ok: true, module: parsed.data };
+}
+// ---------------------------------------------------------------------------
+// Prompting
+// ---------------------------------------------------------------------------
+function retryPreamble(failure) {
+    return (`IMPORTANT — your previous attempt was rejected because it did not ` +
+        `validate against the lab module schema:\n\n${failure}\n\n` +
+        `Fix these problems and respond again with ONLY the corrected JSON object.`);
+}
+/** The ledger slice rendered into one author's prompt (issue #18). */
+function renderLedgerSection(planned, earlierTitles) {
+    const alreadySeen = planned.assumes.length > 0
+        ? planned.assumes.map((a) => `  - ${a}`).join('\n')
+        : '  - nothing about this codebase yet — this is the learner\'s first hands-on module';
+    const references = earlierTitles.length > 0
+        ? earlierTitles.map((t) => `"${t}"`).join(', ')
+        : '(none — this is the first module)';
+    // The opening chapter is the flagship trace, and the catalog lights ITS
+    // system-map as the edition's cover journey (apps/web featured.ts gates
+    // hero eligibility on module 0 carrying a map). Left unstated, that map
+    // came out a coin flip: two Caddy runs hours apart produced four maps and
+    // one. Ask for it by name.
+    const flagship = earlierTitles.length === 0
+        ? `\n- THIS IS THE OPENING CHAPTER — the flagship trace, the first thing anyone reads. Close the trace with a system-map that recaps the path just walked: one node per component the trace actually passed through, edges in the order control moved between them. The catalog lights this map as the edition's cover, so it must be THIS chapter's journey — not a general architecture diagram of the repo.`
+        : '';
+    return `Learner-state ledger — this module is one stop on a longer journey:${flagship}
+- The learner has already seen:
+${alreadySeen}
+  Do not re-explain any of it; build on it (e.g. "you saw X in an earlier module — here is who calls it").
+- This module must teach:
+${planned.teaches.map((t) => `  - ${t}`).join('\n')}
+- Earlier modules you may reference by title: ${references}.${earlierTitles.length > 0
+        ? `
+- CARRY THE THREAD FORWARD. At least once, name a specific thing an earlier chapter already showed the reader — a function, struct, field, or moment, by name — and say what THIS chapter adds to it ("you watched \`ServeHTTP\` hand off to the route chain in ${earlierTitles[0] !== undefined ? `"${earlierTitles[0]}"` : 'the opening chapter'}; here is who builds that chain"). A generic nod ("as we saw earlier") does not count: the reader must be able to place it. Restating something at the same altitude the reader already met it is the failure mode.`
+        : ''}
+- The last widget before the closing quiz must be a callout stating plainly what the learner can now DO that they could not before this module — concrete capabilities ("You can now trace any request from listener to handler", "You can now add and register a config adapter"), not a list of topics covered. Every chapter carries one; a chapter that ends without it breaks the pattern the reader has learned to expect.`;
+}
+/** The style contract every author writes under (issue #18). */
+const STYLE_CONTRACT = `Style contract — how to write every word of this module:
+- Write for a sharp engineer who knows nothing about THIS codebase. Never dumb anything down, and never assume repo-specific knowledge beyond the ledger above.
+- Introduce every abstraction through a concrete instance first: show a real value, call, or file, then name the pattern it is an instance of.
+- Define project-specific jargon the first time it appears.
+- Reach for an analogy whenever it makes a mechanism click — a good module has one or two. Every analogy must be immediately followed by the precise mechanism it stands for, anchored to the code.
+- Teach mechanism and why, not structure alone. "X calls Y" by itself is the failure mode: say what X passes, what Y decides or returns, and why the code is built that way.
+- Teach the craft alongside the behavior. Where a key file exhibits a real code pattern, name it at the moment it appears and anchor it; where the code embodies a system-design decision or an architectural tradeoff, say what was traded away and why this shape won. "why" callouts are the natural home for these. Only name patterns and decisions the code in front of you actually shows — never import textbook material the repo does not have.
+- In prose, wrap every code identifier, symbol, type, function, method, variable, file path, and package name in backticks the moment it appears — e.g. \`ServeHTTP\`, \`caddyhttp.Server\`, \`changeConfig\`, \`internal/caddyhttp/server.go\`. The renderer sets backticked spans as inline code; unbacked identifiers read as ordinary prose. This applies to every prose field (callout/plate bodies, walkthrough commentary, figure captions, quiz explanations, node/state/stage descriptions and edge labels, data-model annotations) — never to the verbatim "code" lines, which are already code.`;
+const CONTENT_CONTRACT = `Field threads — the details a colleague at the next desk would actually give you. The plan assigns each module the threads that are load-bearing THERE (look for them in this module's focus); carry those, and add another only where the material demands it. THE WEAVE RULE governs all of them: a thread is part of this chapter's story, told at the moment it becomes relevant, never appended as a checklist section — and where it touches something an earlier chapter taught, it says so by that chapter's name ("the config reload you traced in Chapter II is what this timeout guards"). Never fabricate:
+- RUN IT. When the module teaches something observable, show how to see it live: the repo's OWN install/run/demo commands, taken verbatim from its README, package scripts, Makefile, or docs, anchored to where they are written. A reader should be able to run what they just learned. Never invent a command the repo does not document.
+- THE NUMBERS THAT MATTER. Surface the constants the code actually embeds — timeouts, sizes, retry counts, thresholds, magic values — anchored, each with why that value matters to behavior the reader has already met.
+- WHEN IT BREAKS. One "warning" callout naming this module's debugging front door: the file, log line, flag, or state a person should inspect FIRST when this subsystem misbehaves, and why, anchored — tied to the mechanism this chapter just taught, not generic advice.
+- HOW IT IS TESTED. Where this module's key files are tested, what those tests pin down, and the exact command the repo's own tooling uses to run just them, anchored to the test files. If the repo has no tests for this area, say nothing rather than inventing.`;
+/**
+ * The diagram budget (founder, 2026-07-25). Prose and code teach only what a
+ * reader can hold in a line; the shapes are what a newcomer draws on a napkin
+ * and keeps. Stated as its own contract so a diagram competes with the
+ * threads for a slot instead of taking whatever is left after them.
+ */
+const SHAPE_CONTRACT = `Draw the shape. A chapter of nothing but prose and code teaches only what a reader can hold in a single line; the shapes are what they will redraw from memory a week later. Where this module's material HAS a shape, carry at least one diagram widget for it — and where it has two, carry two:
+- components and the calls between them → system-map
+- one thing that occupies several states and moves between them → state-machine
+- a fixed sequence of stages, each handing to the next → pipeline
+- a payload, config, or record whose fields carry meaning → data-model
+Skip the diagram only when the module is genuinely one linear read of one file. Never invent structure the code does not have: every node, state, stage, and field is a claim like any other and carries its own anchor, so a shape you cannot anchor is a shape you must not draw.
+
+SHOW THE CODE. Shapes and prose orient the reader; only the source convinces them. At least TWO widgets in this chapter must put real lines in front of the reader — code-walkthrough or code-figure, copied verbatim from the files. A chapter that describes a codebase without ever showing it is a summary, not a lab, however many diagrams and callouts it carries. The only chapter that may fall below two is one whose subject genuinely is not code (a contribution-process chapter, say) — and even there, prefer showing the config, the test, or the CI file to describing it.`;
+/** Exported for prompt-contract tests; not part of the stage's runtime API. */
+export function buildAuthorPrompt(planned, earlierTitles, range) {
+    return `You are authoring one module of a codebase onboarding lab for the repository in your working directory.
+
+Module id: ${planned.id}
+Module title: ${planned.title}
+Focus: ${planned.focus}
+Key files to teach from:
+${planned.keyFiles.map((f) => `- ${f}`).join('\n')}
+
+${renderLedgerSection(planned, earlierTitles)}
+
+${STYLE_CONTRACT}
+
+${CONTENT_CONTRACT}
+
+${SHAPE_CONTRACT}
+
+Explore the repository with the read-only tools available to you (Read, Glob, Grep) — start from the key files, follow the code where the focus leads. Do not modify anything.
+
+When you are done, respond with ONLY a single JSON object (no prose before or after):
+
+{
+  "summary": "<2-3 sentence module summary for a new engineer>",
+  "widgets": [ ...${range.min} to ${range.max} widgets, mixing the types below... ]
+}
+
+Widget types (choose what fits the material; close with the capability callout, then one quiz):
+
+1. Callout — one teachable insight:
+   { "id": "<kebab-id>", "type": "callout", "kind": "why" | "warning" | "connects-to", "title": "<optional>", "body": "<insight>", "anchors": [<anchor>, ...] }
+
+2. Code walkthrough — step through an excerpt:
+   { "id": "<kebab-id>", "type": "code-walkthrough", "title": "<optional>", "code": ["<line 1>", "<line 2>", ...], "source": <anchor for where the excerpt lives>, "steps": [{ "lines": { "start": N, "end": M }, "commentary": { "body": "<what these lines do>", "anchors": [<anchor>] } }] }
+   Copy "code" lines verbatim from the file; step "lines" are 1-based within the excerpt and must not exceed its length.
+
+3. Diagram widgets — one per shape the module's material actually has (see the shape contract above):
+   - system-map: { "id", "type": "system-map", "title", "nodes": [{ "id", "label", "description": "<plain string>", "anchors": [<anchor>, ...] }], "edges": [{ "from", "to", "label": "<plain string>", "anchors": [<anchor>, ...] }] } — CAUTION: unlike the widgets below, a node "description" and an edge "label" are PLAIN STRINGS, never { "body", "anchors" } objects; their anchors go in the sibling "anchors" array. A node with a description (or an edge with a label) requires at least one anchor there. Edge endpoints must name existing node ids.
+   - state-machine: { "id", "type": "state-machine", "title", "states": [{ "id", "label", "description": { "body", "anchors": [...] } }], "transitions": [{ "from", "to", "trigger", "commentary": { "body", "anchors": [...] } }] }
+   - pipeline: { "id", "type": "pipeline", "title", "stages": [{ "id", "label", "description": { "body", "anchors": [...] }, "flow": { "in": "...", "out": "..." } }] }
+   - data-model: { "id", "type": "data-model", "title", "source": <anchor>, "nodes": [{ "name", "type", "example": <optional>, "annotation": { "body", "anchors": [...] }, "children": [...] }] }
+
+4. Code figure — one highlighted excerpt with an anchored caption:
+   { "id": "<kebab-id>", "type": "code-figure", "code": ["..."], "source": <anchor>, "caption": { "body": "<the point of this excerpt>", "anchors": [<anchor>] }, "highlight": { "start": N, "end": M } }
+
+5. Quiz — end-of-module checkpoint (2-4 questions; at least one must ask the reader to PREDICT what the code does for a concrete input or event, not recall what the prose said):
+   { "id": "<kebab-id>", "type": "quiz", "title": "<optional>", "questions": [{ "id": "<kebab-id>", "prompt": "<question>", "options": [{ "id": "<kebab-id>", "label": "<answer>" }, ...>= 2], "correctOptionId": "<option id>", "explanation": { "body": "<why>", "anchors": [<anchor>] } }] }
+
+An <anchor> is { "file": "<repo-relative path>", "symbol": "<identifier>", "lines": { "start": N, "end": M } } — "symbol" and "lines" are optional but sharpen the reference.
+
+Hard requirements — the JSON is machine-validated and rejected on any violation:
+- Every "id" is kebab-case (lowercase letters, digits, hyphens) and unique within its scope.
+- Every teachable claim (callout, commentary, caption, explanation, description, annotation) carries at least one anchor. Where the claim is a { "body", "anchors" } object the anchors go inside it; where it is a plain string (system-map node descriptions, system-map edge labels) the anchors go in the sibling "anchors" array.
+- Anchors are mechanically verified against the repository: "file" must exist repo-relative, "lines" must be a valid 1-based inclusive range in that file, and "symbol" must appear as a whole token inside the anchored region. Only anchor code you actually read — content whose anchors fail verification is dropped from the lab.
+- Do not include a "fingerprint" field on any anchor.
+- Strings are non-empty. Produce ${range.min} to ${range.max} widgets and at least one quiz.`;
+}
+//# sourceMappingURL=authorStage.js.map

package/dist/authorStage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorStage.js","sourceRoot":"","sources":["../src/authorStage.ts"],"names":[],"mappings":"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"}

package/dist/cloneRepo.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Ephemeral clone sandbox for untrusted public repos (Slice 2, #30).
+ *
+ * v1 only **reads** repo files (the generator never executes the repo), so
+ * the threat model is resource abuse and bad URLs — not RCE. This is a
+ * shallow clone into a temp dir with a hard timeout and depth cap; stronger
+ * per-job microVM isolation is deferred to the v2 live-logic widget
+ * (`docs/infra-cost-options.md` §5). `git` itself is injected (`exec`) so the
+ * flow tests without touching the network.
+ */
+export interface CloneResult {
+    /** The local checkout directory (hand to the generator). */
+    dir: string;
+    /** Remove the checkout. Always call it (a `finally`). */
+    cleanup: () => Promise<void>;
+}
+export type ExecResult = {
+    code: number;
+    stderr: string;
+};
+export type ExecFn = (cmd: string, args: readonly string[], opts: {
+    timeoutMs: number;
+}) => Promise<ExecResult>;
+export interface CloneOptions {
+    /** Abort the clone after this long. @default 120_000 */
+    timeoutMs?: number;
+    /** Inject the git runner (tests). @default real `git` via spawn. */
+    exec?: ExecFn;
+    /** Temp root for the checkout. @default os.tmpdir(). */
+    tmpRoot?: string;
+    /**
+     * Installation access token for a private clone (see
+     * `docs/private-repos-design.md`). Passed to git as an `Authorization`
+     * extraheader — never in the URL, so it can't leak into error messages or
+     * the dedup key; `validateRepoUrl` keeps rejecting credentials-in-URL.
+     */
+    accessToken?: string;
+    /**
+     * Check out this exact commit instead of the default branch's tip.
+     *
+     * Verifying a claimed edition means resolving its anchors against the tree
+     * they were written against; clone `HEAD` instead and the repository has
+     * moved on, honest anchors drift, and a sound edition is rejected for a
+     * reason that is not its fault. Must be a full sha — an abbreviation cannot
+     * be fetched by name.
+     */
+    commit?: string;
+}
+export type UrlCheck = {
+    ok: true;
+    url: string;
+    repoKey: string;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Accept only `https://github.com/<owner>/<repo>`. Rejects other hosts, SSH,
+ * credentials-in-URL, and path traversal. Returns the normalized clone URL
+ * and a stable `repoKey` (`owner/repo`) for dedup.
+ */
+export declare function validateRepoUrl(input: string): UrlCheck;
+/**
+ * Validate the URL, shallow-clone into a fresh temp dir, and return the dir
+ * plus a cleanup. On any failure the temp dir is removed before throwing, so
+ * a failed clone never leaks disk.
+ *
+ * With `commit`, the fetch asks for that object by name rather than cloning a
+ * branch: one commit, one tree, no history.
+ */
+export declare function cloneRepo(repoUrl: string, options?: CloneOptions): Promise<CloneResult>;
+//# sourceMappingURL=cloneRepo.d.ts.map

package/dist/cloneRepo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloneRepo.d.ts","sourceRoot":"","sources":["../src/cloneRepo.ts"],"names":[],"mappings":"AAKA;;;;;;;;;GASG;AAEH,MAAM,WAAW,WAAW;IAC1B,4DAA4D;IAC5D,GAAG,EAAE,MAAM,CAAC;IACZ,yDAAyD;IACzD,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED,MAAM,MAAM,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAC1D,MAAM,MAAM,MAAM,GAAG,CACnB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,IAAI,EAAE;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,KACxB,OAAO,CAAC,UAAU,CAAC,CAAC;AAEzB,MAAM,WAAW,YAAY;IAC3B,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,QAAQ,GAChB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC1C;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjC;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,CA2BvD;AAqBD;;;;;;;GAOG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CAiDjG"}

package/dist/cloneRepo.js

@@ -0,0 +1,104 @@
+import { spawn } from 'node:child_process';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+/**
+ * Accept only `https://github.com/<owner>/<repo>`. Rejects other hosts, SSH,
+ * credentials-in-URL, and path traversal. Returns the normalized clone URL
+ * and a stable `repoKey` (`owner/repo`) for dedup.
+ */
+export function validateRepoUrl(input) {
+    let parsed;
+    try {
+        parsed = new URL(input.trim());
+    }
+    catch {
+        return { ok: false, error: `Not a URL: ${input}` };
+    }
+    if (parsed.protocol !== 'https:') {
+        return { ok: false, error: 'Only https:// GitHub URLs are allowed.' };
+    }
+    if (parsed.hostname !== 'github.com') {
+        return { ok: false, error: 'Only github.com repositories are supported.' };
+    }
+    if (parsed.username || parsed.password) {
+        return { ok: false, error: 'URL must not contain credentials.' };
+    }
+    const segments = parsed.pathname.split('/').filter(Boolean);
+    if (segments.length !== 2) {
+        return { ok: false, error: 'Expected https://github.com/<owner>/<repo>.' };
+    }
+    const [owner, repoRaw] = segments;
+    const repo = repoRaw.replace(/\.git$/, '');
+    const nameRe = /^[A-Za-z0-9._-]+$/;
+    if (!nameRe.test(owner) || !nameRe.test(repo) || repo === '.' || repo === '..') {
+        return { ok: false, error: 'Invalid owner or repository name.' };
+    }
+    return { ok: true, url: `https://github.com/${owner}/${repo}.git`, repoKey: `${owner}/${repo}` };
+}
+/** Default git runner: spawn, capture stderr, enforce a kill-on-timeout. */
+const realExec = (cmd, args, opts) => new Promise((resolve) => {
+    const child = spawn(cmd, args, { stdio: ['ignore', 'ignore', 'pipe'] });
+    let stderr = '';
+    const timer = setTimeout(() => child.kill('SIGKILL'), opts.timeoutMs);
+    child.stderr?.on('data', (chunk) => {
+        stderr += chunk.toString();
+    });
+    child.on('error', (err) => {
+        clearTimeout(timer);
+        resolve({ code: 1, stderr: err.message });
+    });
+    child.on('close', (code) => {
+        clearTimeout(timer);
+        resolve({ code: code ?? 1, stderr });
+    });
+});
+/**
+ * Validate the URL, shallow-clone into a fresh temp dir, and return the dir
+ * plus a cleanup. On any failure the temp dir is removed before throwing, so
+ * a failed clone never leaks disk.
+ *
+ * With `commit`, the fetch asks for that object by name rather than cloning a
+ * branch: one commit, one tree, no history.
+ */
+export async function cloneRepo(repoUrl, options = {}) {
+    const check = validateRepoUrl(repoUrl);
+    if (!check.ok)
+        throw new Error(`Invalid repo URL: ${check.error}`);
+    if (options.commit !== undefined && !/^[0-9a-f]{40}$/.test(options.commit)) {
+        throw new Error('A commit to clone must be a full 40-character sha.');
+    }
+    const exec = options.exec ?? realExec;
+    const timeoutMs = options.timeoutMs ?? 120_000;
+    const dir = await mkdtemp(join(options.tmpRoot ?? tmpdir(), 'ramplab-clone-'));
+    const cleanup = () => rm(dir, { recursive: true, force: true });
+    // GitHub installation tokens authenticate as `x-access-token:<token>` over
+    // Basic auth. The extraheader config is scoped to github.com only.
+    const authArgs = options.accessToken === undefined
+        ? []
+        : [
+            '-c',
+            `http.https://github.com/.extraheader=Authorization: Basic ${Buffer.from(`x-access-token:${options.accessToken}`).toString('base64')}`,
+        ];
+    const run = async (args, what) => {
+        const result = await exec('git', args, { timeoutMs });
+        if (result.code !== 0) {
+            await cleanup();
+            throw new Error(`git ${what} failed (exit ${result.code}): ${result.stderr.trim()}`);
+        }
+    };
+    if (options.commit === undefined) {
+        await run([...authArgs, 'clone', '--depth', '1', '--single-branch', '--no-tags', check.url, dir], 'clone');
+        return { dir, cleanup };
+    }
+    // Fetching one object by sha, rather than cloning and then looking for it:
+    // GitHub serves any commit it has by name, so this is a single round trip
+    // for exactly the tree the edition was pressed against, however far the
+    // default branch has moved since.
+    await run(['init', '--quiet', dir], 'init');
+    await run(['-C', dir, 'remote', 'add', 'origin', check.url], 'remote add');
+    await run([...authArgs, '-C', dir, 'fetch', '--depth', '1', 'origin', options.commit], 'fetch');
+    await run(['-C', dir, 'checkout', '--detach', 'FETCH_HEAD'], 'checkout');
+    return { dir, cleanup };
+}
+//# sourceMappingURL=cloneRepo.js.map

package/dist/cloneRepo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloneRepo.js","sourceRoot":"","sources":["../src/cloneRepo.ts"],"names":[],"mappings":"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"}

package/dist/flagship.d.ts

@@ -0,0 +1,62 @@
+import type { LabSpec } from '@ramplab/spec';
+import { type LeadIntake } from './intake.js';
+import type { TraceCandidate } from './mapStage.js';
+import { type PlannedModule } from './planStage.js';
+/**
+ * Pass-1 flagship selection (PLAN.md §4, issue #18): pick the ONE module
+ * worth authoring in the 3–5 minute preview. The flagship is a **trace**:
+ * the most representative candidate "front door" user action the map stage
+ * proposed, authored as "follow this action end to end through the code".
+ *
+ * The selection is mechanical — no model call — and documented here because
+ * it IS the product decision:
+ *
+ * 1. **Trace candidates first.** When the map proposed candidates
+ *    (`MapStageResult.traceCandidates`), the flagship is one of them:
+ *    - **Intake override**: the lead's answers are scanned in priority order
+ *      (`weekOneMastery` before `activeDevelopment`; `gotchas` flavor
+ *      prompts but never pick) and the first candidate whose action/
+ *      description/key files match a hint wins (`basis: 'trace-intake'`).
+ *    - **Otherwise the first candidate wins** (`basis: 'trace'`): the map
+ *      prompt orders candidates most-representative-first, so map order is
+ *      the representativeness ranking.
+ * 2. **Fallback: subsystem centrality over the system map** — the pre-#18
+ *    heuristic, kept for maps with no usable candidates (including reused
+ *    map results captured before trace candidates existed). Candidates are
+ *    anchored nodes; an intake hint match overrides (`basis: 'intake'`);
+ *    otherwise the highest-degree node wins (`basis: 'centrality'`, ties
+ *    keep map order).
+ *
+ * The winner is packaged as a `PlannedModule` (same brief the plan stage
+ * would emit, ledger included) so pass 1 reuses the author stage unchanged,
+ * and pass 2's plan stage pins its module 1 to the same id/title/focus.
+ */
+/** Why the flagship won — trace-based first, node-based fallback. */
+export type FlagshipBasis = 'trace' | 'trace-intake' | 'intake' | 'centrality';
+export interface FlagshipSelection {
+    /** Why it won (see the module doc for the selection order). */
+    basis: FlagshipBasis;
+    /** Trace-based selection: the chosen front-door action. */
+    traceAction?: string;
+    /** Node-based fallback: the chosen system-map node. */
+    nodeId?: string;
+    /** Node-based fallback: incident edge count of the chosen node. */
+    degree?: number;
+    /** When `basis` is `trace-intake` or `intake`: the hint that matched. */
+    matchedHint?: string;
+    /** The authoring brief handed to the author stage. */
+    plannedModule: PlannedModule;
+}
+/** Raised when the map offers nothing teachable to author. */
+export declare class FlagshipSelectionError extends Error {
+    constructor(message: string);
+}
+export declare function selectFlagshipModule(mapSpec: LabSpec, intake?: LeadIntake, traceCandidates?: readonly TraceCandidate[]): FlagshipSelection;
+/**
+ * Select the flagship trace from the map's candidate actions, or `undefined`
+ * when there are no candidates (callers fall back to centrality). Exported
+ * separately because pass 2 uses it too: the plan stage pins its module 1 to
+ * the same selection pass 1 previewed.
+ */
+export declare function selectTraceFlagship(traceCandidates: readonly TraceCandidate[] | undefined, intake?: LeadIntake): FlagshipSelection | undefined;
+//# sourceMappingURL=flagship.d.ts.map

package/dist/flagship.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flagship.d.ts","sourceRoot":"","sources":["../src/flagship.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAiD,MAAM,eAAe,CAAC;AAC5F,OAAO,EAAoB,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,gBAAgB,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,qEAAqE;AACrE,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,cAAc,GAAG,QAAQ,GAAG,YAAY,CAAC;AAE/E,MAAM,WAAW,iBAAiB;IAChC,+DAA+D;IAC/D,KAAK,EAAE,aAAa,CAAC;IACrB,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,aAAa,EAAE,aAAa,CAAC;CAC9B;AAED,8DAA8D;AAC9D,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,OAAO,EAAE,MAAM;CAI5B;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,OAAO,EAChB,MAAM,CAAC,EAAE,UAAU,EACnB,eAAe,CAAC,EAAE,SAAS,cAAc,EAAE,GAC1C,iBAAiB,CAInB;AAMD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,eAAe,EAAE,SAAS,cAAc,EAAE,GAAG,SAAS,EACtD,MAAM,CAAC,EAAE,UAAU,GAClB,iBAAiB,GAAG,SAAS,CAsB/B"}