@ramplab/generator 0.1.0

package/dist/planStage.js

@@ -0,0 +1,275 @@
+import { z } from 'zod';
+import { idSchema } from '@ramplab/spec';
+import { renderIntakeSection } from './intake.js';
+import { extractJson } from './mapStage.js';
+/**
+ * The curriculum-plan stage (PLAN.md §4, pass 2): given the map-stage output
+ * (the system map is the model's index of the repo's subsystems), an agent
+ * plans the lab as a **journey, not a survey** (issue #18). The curriculum
+ * contract, enforced by the parse gate where it can be mechanical:
+ *
+ * - **Module 1 is an end-to-end trace** of one front-door user action. When
+ *   the flagship trace was already selected (see `flagship.ts`), the plan's
+ *   first module must carry its id, and its title/focus are canonicalized
+ *   from the selection after parsing — pass 2's re-authoring of the pass-1
+ *   preview stays canonical instead of re-negotiated per run.
+ * - **Dependency order, concrete to abstract**: each module relies only on
+ *   what earlier modules taught.
+ * - **The learner-state ledger**: every planned module declares `assumes`
+ *   (what the learner knows on arrival) and `teaches` (what it adds). The
+ *   author stage hands each parallel author its slice, buying narrative
+ *   continuity without serializing the fan-out.
+ * - **The final module is always "your first contribution"** (id
+ *   `first-contribution`): starter areas, test conventions, CI gates, PR
+ *   norms — thin if the repo's material is thin, never fabricated.
+ *
+ * The plan is **pipeline-internal state** — it never appears in a lab spec,
+ * so its schema lives here, not in `@ramplab/spec`. Downstream, the author
+ * stage fans out one agent per planned module and the assemble stage merges
+ * the authored modules in plan order.
+ *
+ * Budget semantics: the cap is a **config property, not a repo property**.
+ * The prompt asks for at most `budget.maxModules` modules; if the model
+ * over-delivers anyway, the plan is truncated to the cap after validation.
+ * Truncation drops modules from the end of the middle: the opening trace
+ * and the landing `first-contribution` module always survive, because they
+ * are curriculum invariants, not centrality picks.
+ */
+/** Default cap on planned modules when the config does not set one. */
+export const DEFAULT_MAX_MODULES = 6;
+/** The map stage owns this module id; planned modules must not collide. */
+const RESERVED_MODULE_IDS = new Set(['repo-overview']);
+/**
+ * The mandated landing module (issue #18): every curriculum ends with "your
+ * first contribution" under this id, so its presence is a mechanical check.
+ */
+export const LANDING_MODULE_ID = 'first-contribution';
+/**
+ * Internal Zod schema for one planned module. Deliberately NOT part of
+ * `@ramplab/spec`: the plan (including the learner-state ledger) is an
+ * intermediate artifact between stages and never reaches the lab spec.
+ */
+export const plannedModuleSchema = z.object({
+    /** Stable kebab-case id — becomes the authored module's id in the spec. */
+    id: idSchema,
+    title: z.string().min(1, 'planned module title must be non-empty'),
+    /** What this module must teach — the author agent's brief. */
+    focus: z.string().min(1, 'planned module focus must be non-empty'),
+    /** Repo-relative paths the author agent should start from. */
+    keyFiles: z.array(z.string().min(1)).min(1, 'a planned module needs at least one key file'),
+    /**
+     * Ledger: what the learner already knows on arrival — established by
+     * earlier modules. Empty for the opening trace module.
+     */
+    assumes: z.array(z.string().min(1, 'assumes entries must be non-empty')),
+    /** Ledger: what this module adds to the learner's understanding. */
+    teaches: z
+        .array(z.string().min(1, 'teaches entries must be non-empty'))
+        .min(1, 'a planned module must teach at least one thing'),
+});
+export const curriculumPlanSchema = z
+    .object({
+    modules: z.array(plannedModuleSchema).min(1, 'a plan needs at least one module'),
+})
+    .superRefine((plan, ctx) => {
+    const seen = new Set();
+    plan.modules.forEach((module, index) => {
+        if (seen.has(module.id)) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['modules', index, 'id'],
+                message: `duplicate planned module id "${module.id}"`,
+            });
+        }
+        seen.add(module.id);
+        if (RESERVED_MODULE_IDS.has(module.id)) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['modules', index, 'id'],
+                message: `module id "${module.id}" is reserved for the map stage's overview module`,
+            });
+        }
+    });
+    const last = plan.modules[plan.modules.length - 1];
+    if (last !== undefined && last.id !== LANDING_MODULE_ID) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['modules', plan.modules.length - 1, 'id'],
+            message: `the final module must be the "your first contribution" landing module ` +
+                `with id "${LANDING_MODULE_ID}" (got "${last.id}")`,
+        });
+    }
+});
+/** Raised when the model's output stays schema-invalid after all retries. */
+export class PlanStageError extends Error {
+    attempts;
+    lastFailure;
+    constructor(attempts, lastFailure) {
+        super(`Plan stage failed: model output did not produce a valid curriculum plan after ` +
+            `${attempts} attempt${attempts === 1 ? '' : 's'}.\nLast failure:\n${lastFailure}`);
+        this.name = 'PlanStageError';
+        this.attempts = attempts;
+        this.lastFailure = lastFailure;
+    }
+}
+export async function runPlanStage(runner, repoDir, options) {
+    const maxRetries = options.maxRetries ?? 1;
+    const maxAttempts = 1 + Math.max(0, maxRetries);
+    const maxModules = options.budget?.maxModules ?? DEFAULT_MAX_MODULES;
+    const basePrompt = buildPlanPrompt(options.mapSpec, maxModules, options.budget?.scopeHints, options.intake, options.traceModule);
+    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: 'plan',
+            model: options.model,
+            repoDir,
+            prompt,
+            attempt,
+        });
+        if (response.costUsd !== undefined) {
+            costUsd = (costUsd ?? 0) + response.costUsd;
+        }
+        const outcome = parsePlan(response.output, options.traceModule);
+        if (outcome.ok) {
+            return { plan: capPlan(outcome.plan, maxModules), attempts: attempt, costUsd };
+        }
+        lastFailure = outcome.failure;
+    }
+    throw new PlanStageError(maxAttempts, lastFailure);
+}
+/**
+ * Enforce the budget mechanically, preserving the curriculum invariants:
+ * the opening trace (head of the plan) and the landing `first-contribution`
+ * module (tail) always survive; over-delivery is trimmed from the end of
+ * the middle. This makes the cap a config guarantee rather than a hope
+ * about model obedience.
+ */
+function capPlan(plan, maxModules) {
+    if (plan.modules.length <= maxModules)
+        return plan;
+    const landing = plan.modules[plan.modules.length - 1];
+    return { modules: [...plan.modules.slice(0, Math.max(0, maxModules - 1)), landing] };
+}
+/**
+ * The parse gate: schema validation (ledger fields, landing module, ids)
+ * plus the flagship-trace contract when a trace module was pre-selected —
+ * the first module must carry the trace's id, and its title/focus are then
+ * overwritten with the canonical selection so the trace's identity is owned
+ * by flagship selection, not re-negotiated by the planner. The planner still
+ * owns the trace module's keyFiles (it explored the repo) and its ledger.
+ */
+export function parsePlan(output, traceModule) {
+    const json = extractJson(output);
+    if (json === undefined) {
+        return { ok: false, failure: 'The output did not contain a parseable JSON object.' };
+    }
+    const parsed = curriculumPlanSchema.safeParse(json);
+    if (!parsed.success) {
+        return { ok: false, failure: z.prettifyError(parsed.error) };
+    }
+    const plan = parsed.data;
+    if (traceModule !== undefined) {
+        const first = plan.modules[0];
+        if (first.id !== traceModule.id) {
+            return {
+                ok: false,
+                failure: `The first module must be the already-selected flagship trace module ` +
+                    `with id "${traceModule.id}" (got "${first.id}").`,
+            };
+        }
+        plan.modules[0] = { ...first, title: traceModule.title, focus: traceModule.focus };
+    }
+    return { ok: true, plan };
+}
+// ---------------------------------------------------------------------------
+// Prompting
+// ---------------------------------------------------------------------------
+function retryPreamble(failure) {
+    return (`IMPORTANT — your previous attempt was rejected because it did not ` +
+        `validate against the curriculum-plan schema:\n\n${failure}\n\n` +
+        `Fix these problems and respond again with ONLY the corrected JSON object.`);
+}
+/** Render the map stage's system map as compact context for the planner. */
+function describeSystemMap(mapSpec) {
+    const lines = [];
+    for (const module of mapSpec.base.modules) {
+        for (const widget of module.widgets) {
+            if (widget.type !== 'system-map')
+                continue;
+            for (const node of widget.nodes) {
+                const files = (node.anchors ?? []).map((a) => a.file).join(', ');
+                lines.push(`- ${node.label} (${node.id})` +
+                    (node.description !== undefined ? `: ${node.description}` : '') +
+                    (files.length > 0 ? ` [${files}]` : ''));
+            }
+            for (const edge of widget.edges) {
+                lines.push(`- edge ${edge.from} -> ${edge.to}${edge.label !== undefined ? `: ${edge.label}` : ''}`);
+            }
+        }
+    }
+    return lines.length > 0 ? lines.join('\n') : '(no system map available)';
+}
+function buildPlanPrompt(mapSpec, maxModules, scopeHints, intake, traceModule) {
+    const hints = scopeHints !== undefined && scopeHints.length > 0
+        ? `\nScope hints from the onboarding lead — respect them when choosing and ordering modules:\n${scopeHints.map((h) => `- ${h}`).join('\n')}\n`
+        : '';
+    const traceContract = traceModule !== undefined
+        ? `The trace has already been selected — your FIRST module MUST use exactly this id (its title and focus are fixed; restate them verbatim):
+   - id: ${traceModule.id}
+   - title: ${traceModule.title}
+   - focus: ${traceModule.focus}
+   Plan its "keyFiles" from the files along the action's path (start from: ${traceModule.keyFiles.join(', ')}), and fill in its ledger ("assumes" is [] — the learner arrives knowing nothing).`
+        : `Pick ONE "front door" user action — a real scenario a user triggers from outside (a request served, a file sent, a command run) — and make module 1 follow it end to end through the code, entry point to effect, before anything abstract.`;
+    return `You are planning the curriculum for a codebase onboarding lab — a JOURNEY that takes a sharp engineer from zero knowledge of this repository to first-meaningful-PR readiness. A previous mapping pass produced this system map of the repository in your working directory:
+
+${describeSystemMap(mapSpec)}
+
+Explore the repository with the read-only tools available to you (Read, Glob, Grep) to confirm what each module should teach. Do not modify anything.
+${renderIntakeSection(intake)}${hints}
+Curriculum contract — every plan must satisfy all five points:
+
+1. MODULE 1 IS AN END-TO-END TRACE. ${traceContract}
+
+2. DEPENDENCY ORDER, CONCRETE TO ABSTRACT. Order the modules so each relies only on what earlier modules taught. Concrete mechanisms come before the abstractions and architecture built from them; a learner must meet every concept through a concrete instance before any module treats it abstractly. Do not plan a "most important areas" survey — plan a path.
+
+3. THE LEARNER-STATE LEDGER. Every module declares:
+   - "assumes": what the learner already knows on arrival — only things an EARLIER module in this plan teaches (empty for module 1).
+   - "teaches": what this module adds. Together, the "teaches" lists are the whole journey.
+
+4. THE CRAFT IS CURRICULUM. The journey must teach how this codebase is BUILT, not only what it does — woven into the modules where each is most concrete, never quarantined into one abstract survey module:
+   - the CODE PATTERNS the repo actually uses, called by their names at the places they occur (a plugin registry, dependency injection, a worker pool — whatever this repo truly exhibits);
+   - the SYSTEM DESIGN decisions the code embodies and the tradeoffs they bought;
+   - the ARCHITECTURE'S rationale: not just what talks to what, but why it is shaped that way.
+   Reflect this in the modules' "focus" and "teaches" entries so the authoring pass delivers it. Only claim patterns and decisions the code actually shows — never import textbook patterns the repo does not have.
+
+   DISTRIBUTE THE FIELD THREADS. Four field threads run through an edition: RUN IT (the repo's own run/demo commands), THE NUMBERS THAT MATTER (embedded constants and why), WHEN IT BREAKS (the subsystem's debugging front door), and HOW IT IS TESTED (where the tests live and how to run just them). Assign each thread to the ONE OR TWO modules where it is load-bearing — run-it belongs where the reader first has something to run, when-it-breaks where the operational risk lives, how-it-is-tested where the test suite actually concentrates — and NAME the assigned threads in those modules' "focus". A module stamped with all four reads as a checklist and breaks the journey; a thread assigned nowhere is a gap.
+
+5. THE FINAL MODULE IS "YOUR FIRST CONTRIBUTION", id exactly "${LANDING_MODULE_ID}". It teaches where starter work lives, the repo's test conventions and how to run them, the CI gates a PR must pass, and contribution/PR norms.${intake !== undefined ? ` The onboarding lead's "active development" and "week-one" answers above tell you which starter areas matter most.` : ''} Ground every claim in material that actually exists in the repo (CONTRIBUTING/docs, CI configs, test directories, tooling). If the repo offers little such material, keep this module thin — NEVER fabricate conventions the repo does not have.
+
+Hard budget: plan AT MOST ${maxModules} module${maxModules === 1 ? '' : 's'} INCLUDING the trace and the "${LANDING_MODULE_ID}" module. If you over-deliver, modules are discarded from the end of the middle (the trace and the landing module always survive) — make every middle module earn its slot.
+
+When you are done, respond with ONLY a single JSON object (no prose before or after) with exactly this shape:
+
+{
+  "modules": [
+    {
+      "id": "<kebab-case-id, stable across regenerations>",
+      "title": "<module title a learner sees>",
+      "focus": "<2-4 sentences: what this module must teach and why it matters>",
+      "keyFiles": ["<repo-relative path>", "..."],
+      "assumes": ["<something an earlier module taught>", "..."],
+      "teaches": ["<something this module adds>", "..."]
+    }
+  ]
+}
+
+Hard requirements — the JSON is machine-validated and rejected on any violation:
+- Every "id" is kebab-case (lowercase letters, digits, hyphens), unique, and NOT "repo-overview" (that id is reserved for the intro module).${traceModule !== undefined ? `\n- The FIRST module's id is "${traceModule.id}".` : ''}
+- The LAST module's id is "${LANDING_MODULE_ID}".
+- Every module has "assumes" (a list, may be empty) and "teaches" (at least one entry).
+- "keyFiles" lists 1-6 repo-relative paths to files that actually exist — only list files you confirmed.
+- Strings are non-empty. At most ${maxModules} entries in "modules".`;
+}
+//# sourceMappingURL=planStage.js.map

package/dist/planStage.js.map

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

package/dist/progress.d.ts

@@ -0,0 +1,45 @@
+import type { LabSpec } from '@ramplab/spec';
+import type { GenerationStageName } from './pipeline.js';
+/**
+ * Progress streaming for the two-pass runtime (PLAN.md §4).
+ *
+ * The `onProgress` callback is **the streaming seam**: pass 1's "renders as
+ * it streams in" experience is a caller subscribing to these events — no
+ * network or server transport lives in this package. A server slice later
+ * forwards the same events over SSE/WebSocket; the CLI prints them; tests
+ * assert on them.
+ *
+ * Event vocabulary (deliberately small):
+ * - `stage-started` / `stage-completed` — pipeline stage boundaries.
+ * - `module-authored` — one authored module landed (fan-out progress).
+ * - `spec-updated` — carries a **complete, schema-valid, anchor-resolved
+ *   lab spec** reflecting everything generated so far, so a renderer can
+ *   display each snapshot as-is without merging deltas.
+ *
+ * Callbacks are invoked synchronously and are not awaited; a throwing
+ * callback would abort the run, so callers should keep handlers cheap.
+ */
+/** Which pass of the two-pass runtime emitted an event. */
+export type GenerationPass = 'pass1' | 'pass2';
+export type GenerationProgressEvent = {
+    type: 'stage-started';
+    pass: GenerationPass;
+    stage: GenerationStageName;
+} | {
+    type: 'stage-completed';
+    pass: GenerationPass;
+    stage: GenerationStageName;
+} | {
+    type: 'module-authored';
+    pass: GenerationPass;
+    moduleId: string;
+    /** Attempts spent on this module (1 = no retry needed). */
+    attempts: number;
+} | {
+    type: 'spec-updated';
+    pass: GenerationPass;
+    /** A valid, anchor-resolved snapshot — renderable as-is. */
+    spec: LabSpec;
+};
+export type ProgressCallback = (event: GenerationProgressEvent) => void;
+//# sourceMappingURL=progress.d.ts.map

package/dist/progress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.d.ts","sourceRoot":"","sources":["../src/progress.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEzD;;;;;;;;;;;;;;;;;;GAkBG;AAEH,2DAA2D;AAC3D,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,OAAO,CAAC;AAE/C,MAAM,MAAM,uBAAuB,GAC/B;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,IAAI,EAAE,cAAc,CAAC;IAAC,KAAK,EAAE,mBAAmB,CAAA;CAAE,GAC3E;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,IAAI,EAAE,cAAc,CAAC;IAAC,KAAK,EAAE,mBAAmB,CAAA;CAAE,GAC7E;IACE,IAAI,EAAE,iBAAiB,CAAC;IACxB,IAAI,EAAE,cAAc,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;CAClB,GACD;IACE,IAAI,EAAE,cAAc,CAAC;IACrB,IAAI,EAAE,cAAc,CAAC;IACrB,4DAA4D;IAC5D,IAAI,EAAE,OAAO,CAAC;CACf,CAAC;AAEN,MAAM,MAAM,gBAAgB,GAAG,CAAC,KAAK,EAAE,uBAAuB,KAAK,IAAI,CAAC"}

package/dist/progress.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=progress.js.map

package/dist/progress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.js","sourceRoot":"","sources":["../src/progress.ts"],"names":[],"mappings":""}

package/dist/repoCommit.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The commit a repository directory is sitting at (founder, 2026-07-26).
+ *
+ * Stamped onto a pressed spec as `commit`, because anchors are only checkable
+ * against the tree they were written against. Anyone re-verifying a spec later
+ * needs to fetch that exact tree; without it they clone `HEAD`, the repository
+ * has moved on, and honest anchors fail.
+ *
+ * Deliberately best-effort and silent: a directory that is not a git checkout
+ * is a perfectly valid thing to press (a tarball, a vendored copy), and it
+ * would be wrong to fail a pressing over provenance nobody asked for. The
+ * consequence is stated where it lands — an edition with no commit cannot be
+ * verified later, so it cannot take the public shelf.
+ */
+export declare function readRepoCommit(repoDir: string): string | undefined;
+/**
+ * True when the working tree has uncommitted changes. A spec pressed from a
+ * dirty tree describes code that exists on exactly one machine, so its anchors
+ * can never be re-verified from the commit alone — worth knowing before an
+ * edition is offered to the public shelf.
+ */
+export declare function isRepoDirty(repoDir: string): boolean;
+/**
+ * The repository a checkout came from, canonicalized (founder, 2026-07-26).
+ *
+ * A pressed spec has to name its repository or nothing can ever check it: the
+ * claim route needs somewhere to clone from, and without this every edition
+ * pressed on someone's own machine reads as "does not name a repository" and
+ * is capped below the public shelf forever. The hosted press has always
+ * stamped it from the URL it was given; a local press reads it from the
+ * remote.
+ *
+ * Only GitHub, because that is what the library can actually fetch and
+ * re-resolve anchors against. Naming a remote we cannot clone would promise a
+ * check we are unable to perform, so a repository elsewhere is left unnamed
+ * and the edition stays private or unlisted, which is the honest outcome.
+ * `https` and `ssh` remotes of the same project canonicalize to one string, so
+ * a spec does not say two different things depending on how someone cloned.
+ */
+export declare function readRepoRemote(repoDir: string): string | undefined;
+//# sourceMappingURL=repoCommit.d.ts.map

package/dist/repoCommit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repoCommit.d.ts","sourceRoot":"","sources":["../src/repoCommit.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAYlE;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAYpD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAclE"}

package/dist/repoCommit.js

@@ -0,0 +1,84 @@
+import { execFileSync } from 'node:child_process';
+import { parseGithubRepo } from '@ramplab/spec';
+/**
+ * The commit a repository directory is sitting at (founder, 2026-07-26).
+ *
+ * Stamped onto a pressed spec as `commit`, because anchors are only checkable
+ * against the tree they were written against. Anyone re-verifying a spec later
+ * needs to fetch that exact tree; without it they clone `HEAD`, the repository
+ * has moved on, and honest anchors fail.
+ *
+ * Deliberately best-effort and silent: a directory that is not a git checkout
+ * is a perfectly valid thing to press (a tarball, a vendored copy), and it
+ * would be wrong to fail a pressing over provenance nobody asked for. The
+ * consequence is stated where it lands — an edition with no commit cannot be
+ * verified later, so it cannot take the public shelf.
+ */
+export function readRepoCommit(repoDir) {
+    try {
+        const sha = execFileSync('git', ['rev-parse', 'HEAD'], {
+            cwd: repoDir,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 5_000,
+        }).trim();
+        return /^[0-9a-f]{40}$/.test(sha) ? sha : undefined;
+    }
+    catch {
+        return undefined; // not a checkout, no git, shallow oddity: not our problem
+    }
+}
+/**
+ * True when the working tree has uncommitted changes. A spec pressed from a
+ * dirty tree describes code that exists on exactly one machine, so its anchors
+ * can never be re-verified from the commit alone — worth knowing before an
+ * edition is offered to the public shelf.
+ */
+export function isRepoDirty(repoDir) {
+    try {
+        const status = execFileSync('git', ['status', '--porcelain'], {
+            cwd: repoDir,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 5_000,
+        });
+        return status.trim().length > 0;
+    }
+    catch {
+        return false; // not a checkout: nothing to be dirty about
+    }
+}
+/**
+ * The repository a checkout came from, canonicalized (founder, 2026-07-26).
+ *
+ * A pressed spec has to name its repository or nothing can ever check it: the
+ * claim route needs somewhere to clone from, and without this every edition
+ * pressed on someone's own machine reads as "does not name a repository" and
+ * is capped below the public shelf forever. The hosted press has always
+ * stamped it from the URL it was given; a local press reads it from the
+ * remote.
+ *
+ * Only GitHub, because that is what the library can actually fetch and
+ * re-resolve anchors against. Naming a remote we cannot clone would promise a
+ * check we are unable to perform, so a repository elsewhere is left unnamed
+ * and the edition stays private or unlisted, which is the honest outcome.
+ * `https` and `ssh` remotes of the same project canonicalize to one string, so
+ * a spec does not say two different things depending on how someone cloned.
+ */
+export function readRepoRemote(repoDir) {
+    let url;
+    try {
+        url = execFileSync('git', ['remote', 'get-url', 'origin'], {
+            cwd: repoDir,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 5_000,
+        }).trim();
+    }
+    catch {
+        return undefined; // no remote, no git, not a checkout: not our problem
+    }
+    const ref = parseGithubRepo(url);
+    return ref === undefined ? undefined : `https://github.com/${ref.owner}/${ref.name}`;
+}
+//# sourceMappingURL=repoCommit.js.map

package/dist/repoCommit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repoCommit.js","sourceRoot":"","sources":["../src/repoCommit.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEhD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe;IAC5C,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,KAAK,EAAE,CAAC,WAAW,EAAE,MAAM,CAAC,EAAE;YACrD,GAAG,EAAE,OAAO;YACZ,QAAQ,EAAE,MAAM;YAChB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC;YACnC,OAAO,EAAE,KAAK;SACf,CAAC,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,gBAAgB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;IACtD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC,CAAC,0DAA0D;IAC9E,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,EAAE,CAAC,QAAQ,EAAE,aAAa,CAAC,EAAE;YAC5D,GAAG,EAAE,OAAO;YACZ,QAAQ,EAAE,MAAM;YAChB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC;YACnC,OAAO,EAAE,KAAK;SACf,CAAC,CAAC;QACH,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC,CAAC,4CAA4C;IAC5D,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe;IAC5C,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,YAAY,CAAC,KAAK,EAAE,CAAC,QAAQ,EAAE,SAAS,EAAE,QAAQ,CAAC,EAAE;YACzD,GAAG,EAAE,OAAO;YACZ,QAAQ,EAAE,MAAM;YAChB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC;YACnC,OAAO,EAAE,KAAK;SACf,CAAC,CAAC,IAAI,EAAE,CAAC;IACZ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC,CAAC,qDAAqD;IACzE,CAAC;IACD,MAAM,GAAG,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;IACjC,OAAO,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,sBAAsB,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC;AACvF,CAAC"}

package/dist/repoSize.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Right-sizing the curriculum to the repository (founder, 2026-07-14): every
+ * edition was exactly the module cap because a budget reads as a quota to the
+ * planner, so a thousand-line game and a hundred-thousand-line monorepo got
+ * identical spines. The plan budget now scales with what the clone actually
+ * holds. Mechanical and cheap: one directory walk, no model involved.
+ */
+export interface RepoSizeStats {
+    /** Source-ish files counted (binaries and vendored trees skipped). */
+    files: number;
+    /** Their summed size in bytes. */
+    bytes: number;
+}
+export declare function measureRepo(dir: string): RepoSizeStats;
+/**
+ * Planned (authored) modules for a repo of this size. The assembled edition
+ * adds the overview module on top, so the reader sees one more chapter than
+ * this number: tiers 4/5/6/7 read as editions of 5/6/7/8 chapters. A tier is
+ * taken when EITHER measure clears it; both file count and volume signal
+ * teachable surface.
+ */
+export declare function plannedModulesFor(stats: RepoSizeStats): number;
+//# sourceMappingURL=repoSize.d.ts.map

package/dist/repoSize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repoSize.d.ts","sourceRoot":"","sources":["../src/repoSize.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AAEH,MAAM,WAAW,aAAa;IAC5B,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAC;IACd,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;CACf;AAwBD,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CA4BtD;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAO9D"}

package/dist/repoSize.js

@@ -0,0 +1,74 @@
+import { readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+/** Directories that say nothing about how much there is to TEACH. */
+const SKIPPED_DIRS = new Set([
+    '.git',
+    'node_modules',
+    'vendor',
+    'dist',
+    'build',
+    'out',
+    'target',
+    '.next',
+    'coverage',
+]);
+/** Extensions that are clearly not teachable source. */
+const SKIPPED_EXTENSIONS = new Set([
+    '.png', '.jpg', '.jpeg', '.gif', '.webp', '.ico', '.svg',
+    '.woff', '.woff2', '.ttf', '.otf', '.eot',
+    '.mp3', '.mp4', '.ogg', '.wav', '.webm',
+    '.zip', '.gz', '.tar', '.jar', '.wasm',
+    '.lock', '.min.js', '.map', '.pdf',
+]);
+export function measureRepo(dir) {
+    const stats = { files: 0, bytes: 0 };
+    const walk = (current) => {
+        let entries;
+        try {
+            entries = readdirSync(current, { withFileTypes: true });
+        }
+        catch {
+            return; // unreadable directory: not teachable either
+        }
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                if (!SKIPPED_DIRS.has(entry.name))
+                    walk(join(current, entry.name));
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            const name = entry.name.toLowerCase();
+            const ext = name.slice(name.lastIndexOf('.'));
+            if (SKIPPED_EXTENSIONS.has(ext) || name.endsWith('.min.js'))
+                continue;
+            try {
+                stats.files += 1;
+                stats.bytes += statSync(join(current, entry.name)).size;
+            }
+            catch {
+                stats.files -= 0; // stat raced a deletion: skip silently
+            }
+        }
+    };
+    walk(dir);
+    return stats;
+}
+/**
+ * Planned (authored) modules for a repo of this size. The assembled edition
+ * adds the overview module on top, so the reader sees one more chapter than
+ * this number: tiers 4/5/6/7 read as editions of 5/6/7/8 chapters. A tier is
+ * taken when EITHER measure clears it; both file count and volume signal
+ * teachable surface.
+ */
+export function plannedModulesFor(stats) {
+    const tier = (files, bytes) => stats.files >= files || stats.bytes >= bytes;
+    if (tier(900, 8_000_000))
+        return 7;
+    if (tier(200, 1_500_000))
+        return 6;
+    if (tier(40, 300_000))
+        return 5;
+    return 4;
+}
+//# sourceMappingURL=repoSize.js.map

package/dist/repoSize.js.map

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