create-nola-lang 0.1.11 → 0.1.12

package/README.md

@@ -10,17 +10,23 @@ npm start        # runs offline via a committed replay ledger - no API key neede
 ```
 
 Interactively the flow asks for a name (Enter keeps the default), a template,
-an inference provider (Nola first — 25 free runs, no account or provider key —
-then OpenAI, Anthropic, Gemini, or skip), whether to set up your editor and
-coding agents (yes opens one list: VS Code, preselected, writes `.vscode/`
-with a debug config + the extension recommendation; coding-agent skills,
-Claude Code preselected), and — once the files are written, when an editor
-was chosen — whether to install dependencies and open the project in VS Code
-right away (on `src/main.ts`, whose opening comment lists the next steps:
-F5 to run, a breakpoint to debug, the recommended extension).
+an inference provider (`nola: dev` first — 25 free hosted runs, no API key required, suited for dev experiments —
+then OpenAI, Anthropic, Gemini, typesafe.ai — bracketed with the caveat that
+it serves literal unions and booleans only — or skip), and — once the files are
+written, unless `--ide none` — whether to install dependencies and open the
+project in VS Code right away (just the install when VS Code's `code` command
+is not on PATH; on the entry file — `src/main.tsi`, or
+`src/main.ts` for `typescript-interop` — whose opening comment lists the next
+steps: F5 to run, a breakpoint to debug, the recommended extension). The editor
+setup (`.vscode/` with a debug config + the extension recommendation) and the
+coding-agent skill (`.agents/skills/nola/`, with `.claude/skills/nola` a
+symlink to it for Claude Code) are written without a question; `--ide none` and
+`--agents none` opt out, `--agents claude,universal,agents-md` adds `AGENTS.md`.
 
-You get a typed extraction example (`src/person.tsi` + a plain-TS consumer),
-`nola.config.ts`, tsconfig, and a recorded replay ledger so the first run
-works without any API key. `npm create nola` is a short alias of this package
-(`create-nola`); `nola init` (from the `nola-lang` package) lays
-down the same starter.
+You get one template per feature — `feature-extraction` (the default) is one
+`src/main.tsi` with a top-level `ask`, `function-calling` the same with a call
+intent over an async function in `src/tickets.ts`, `typescript-interop` is
+`src/person.tsi` plus a plain-TS consumer — with `nola.config.ts`, tsconfig,
+and a recorded replay ledger so the first run works without any API key. `npm create nola`
+is a short alias of this package (`create-nola`); `nola init` (from the
+`nola-lang` package) lays down the same templates.

package/dist/agents.d.ts

@@ -9,6 +9,13 @@ export declare const SKILL_AGENTS_QUESTION = "Set up coding agents? (Space toggl
  * that Cursor, Copilot, Codex, Gemini CLI and most other agents read.
  */
 export declare const SKILL_DIRS: Readonly<Record<Exclude<AgentId, "agents-md">, string>>;
+/**
+ * The Claude Code directory is a LINK to the universal one (2026-09-18): one
+ * copy of the content, `.claude/skills/nola → ../../.agents/skills/nola`,
+ * relative so the project can move. Only when both targets are written — a
+ * `claude`-only install has nothing to link to and stays a copy.
+ */
+export declare const CLAUDE_LINK_TARGET: string;
 /** Shared option list for every agents multiselect. */
 export declare const AGENT_OPTIONS: {
     value: AgentId;
@@ -30,7 +37,12 @@ export interface SkillSource {
 export declare function readSkillSource(): Promise<SkillSource>;
 /** The `## Nola` section for AGENTS.md — also the paste snippet when skipped. */
 export declare function agentsSection(s: SkillSource, version: string): string;
-/** The interactive preselection: both skill copies, so a plain Enter covers every skills-aware agent. */
+/**
+ * What the scaffold writes when `--agents` is absent (the setup question is
+ * retired, 2026-09-18) and `nola skill install`'s preselection: both skill
+ * targets — the universal directory plus the Claude Code link — so every
+ * skills-aware agent is covered. AGENTS.md stays opt-in.
+ */
 export declare function defaultAgents(_targetDir: string): AgentId[];
 /** "all" | "none" | comma list of ids; unknown ids throw listing valid values. */
 export declare function parseAgentsFlag(value: string): AgentId[];

package/dist/agents.js

@@ -1,6 +1,6 @@
 import { existsSync } from "node:fs";
-import { mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
-import { dirname, join, resolve } from "node:path";
+import { lstat, mkdir, readdir, readFile, realpath, rm, symlink, writeFile } from "node:fs/promises";
+import { dirname, join, posix, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { ownVersion } from "./scaffold.js";
 export const AGENT_IDS = ["claude", "universal", "agents-md"];
@@ -16,6 +16,13 @@ export const SKILL_DIRS = {
     claude: ".claude/skills/nola",
     universal: ".agents/skills/nola",
 };
+/**
+ * The Claude Code directory is a LINK to the universal one (2026-09-18): one
+ * copy of the content, `.claude/skills/nola → ../../.agents/skills/nola`,
+ * relative so the project can move. Only when both targets are written — a
+ * `claude`-only install has nothing to link to and stays a copy.
+ */
+export const CLAUDE_LINK_TARGET = posix.relative(posix.dirname(SKILL_DIRS.claude), SKILL_DIRS.universal);
 /** Shared option list for every agents multiselect. */
 export const AGENT_OPTIONS = [
     { value: "claude", label: "Claude Code", hint: ".claude/skills/nola/ (the only directory Claude Code reads)" },
@@ -63,7 +70,12 @@ export function agentsSection(s, version) {
 function agentsMd(s, version) {
     return `# AGENTS.md\n\n${agentsSection(s, version)}`;
 }
-/** The interactive preselection: both skill copies, so a plain Enter covers every skills-aware agent. */
+/**
+ * What the scaffold writes when `--agents` is absent (the setup question is
+ * retired, 2026-09-18) and `nola skill install`'s preselection: both skill
+ * targets — the universal directory plus the Claude Code link — so every
+ * skills-aware agent is covered. AGENTS.md stays opt-in.
+ */
 export function defaultAgents(_targetDir) {
     return ["claude", "universal"];
 }
@@ -104,6 +116,69 @@ function disposition(path, existing, version, force) {
         stale: true,
     };
 }
+const untouched = (path) => ({
+    kind: "kept",
+    note: `${path} already exists and was not generated by nola — left untouched`,
+    stale: false,
+});
+/**
+ * Make `.claude/skills/nola` the link to `.agents/skills/nola`. What may
+ * already be there: the link itself (up to date); a link elsewhere or an
+ * unstamped copy (the user's, left alone); a stamped copy (reported, replaced
+ * under --force); a plain FILE holding the link text — what a checkout
+ * without symlink support (Windows, core.symlinks=false) makes of a committed
+ * link — or a dangling link, both ours to repair without --force. A directory
+ * symlink needs Developer Mode or admin on Windows: that failure is reported
+ * and the caller falls back to a copy.
+ */
+async function linkClaudeDir(root, version, force) {
+    const base = SKILL_DIRS.claude;
+    const link = join(root, ...base.split("/"));
+    const existing = await lstat(link).catch(() => undefined);
+    if (existing?.isSymbolicLink()) {
+        const target = join(root, ...SKILL_DIRS.universal.split("/"));
+        const [resolved, wanted] = await Promise.all([
+            realpath(link).catch(() => undefined),
+            realpath(target).catch(() => undefined),
+        ]);
+        if (resolved !== undefined && resolved === wanted) {
+            return { kind: "kept", note: `${base} is a link to ${SKILL_DIRS.universal} — up to date`, stale: false };
+        }
+        if (resolved !== undefined)
+            return untouched(base);
+        await rm(link); // dangling: nothing behind it to keep
+    }
+    else if (existing?.isDirectory()) {
+        const marker = join(link, "SKILL.md");
+        const found = existsSync(marker) ? STAMP_RE.exec(await readFile(marker, "utf8")) : null;
+        if (!found)
+            return untouched(base);
+        if (!force) {
+            const note = found[1] === version
+                ? `${base} is a copy (v${version}) — re-run with --force to replace it with a link to ${SKILL_DIRS.universal}`
+                : `${base}/SKILL.md is stale (v${found[1]} → v${version}) — re-run with --force to replace it`;
+            return { kind: "kept", note, stale: true };
+        }
+        await rm(link, { recursive: true });
+    }
+    else if (existing?.isFile()) {
+        if ((await readFile(link, "utf8")).trim() !== CLAUDE_LINK_TARGET)
+            return untouched(base);
+        await rm(link);
+    }
+    else if (existing) {
+        return untouched(base);
+    }
+    await mkdir(dirname(link), { recursive: true });
+    try {
+        await symlink(CLAUDE_LINK_TARGET, link, "dir");
+    }
+    catch (err) {
+        const code = err.code ?? "error";
+        return { kind: "unlinkable", note: `could not link ${base} → ${SKILL_DIRS.universal} (${code}) — wrote a copy instead` };
+    }
+    return { kind: "linked" };
+}
 /** Copy the canonical skill dir verbatim (stamp aside) into `<root>/<base>/`. */
 async function writeSkillDir(root, base, s, version) {
     const dir = join(root, ...base.split("/"));
@@ -130,20 +205,43 @@ export async function writeAgentSkills(targetDir, agents, opts = {}) {
     const removed = [];
     const skipped = [];
     let stale = false;
-    for (const id of ["claude", "universal"]) {
-        if (!agents.includes(id))
-            continue;
-        const base = SKILL_DIRS[id];
-        const marker = join(root, ...base.split("/"), "SKILL.md");
+    /** A real copy at `<base>` — classified first, never blindly overwritten. */
+    const copy = async (base) => {
+        const dir = join(root, ...base.split("/"));
+        const marker = join(dir, "SKILL.md");
         if (existsSync(marker)) {
             const d = disposition(`${base}/SKILL.md`, await readFile(marker, "utf8"), version, force);
             if (!d.write) {
                 skipped.push(d.note);
                 stale ||= d.stale;
-                continue;
+                return;
             }
         }
+        else if ((await lstat(dir).catch(() => undefined))?.isSymbolicLink()) {
+            await rm(dir); // a dangling link — nothing to keep, and mkdir would follow it
+        }
         wrote.push(...(await writeSkillDir(root, base, source, version)));
+    };
+    // universal first: it is the one real copy the claude link points at
+    if (agents.includes("universal"))
+        await copy(SKILL_DIRS.universal);
+    if (agents.includes("claude")) {
+        if (!agents.includes("universal")) {
+            await copy(SKILL_DIRS.claude);
+        }
+        else {
+            const link = await linkClaudeDir(root, version, force);
+            if (link.kind === "linked") {
+                wrote.push(`${SKILL_DIRS.claude} → ${SKILL_DIRS.universal}`);
+            }
+            else {
+                skipped.push(link.note);
+                if (link.kind === "kept")
+                    stale ||= link.stale;
+                else
+                    await copy(SKILL_DIRS.claude);
+            }
+        }
     }
     if (agents.includes("universal")) {
         // Stamped legacy adapters are ours: superseded by .agents/skills, removed under --force.

package/dist/checkout.d.ts

@@ -21,4 +21,24 @@ export declare const CHECKOUT_LINKED_PACKAGES: readonly string[];
  * Returns the linked package names.
  */
 export declare function linkCheckoutPackages(dir: string, root: string): Promise<string[]>;
+/**
+ * The skipFiles glob the in-repo dogfood launch configs carry. Node resolves
+ * a junction to its real path, so a linked scaffold runs the runtime from
+ * <checkout>/packages/\*\/dist — outside node_modules, which is all the
+ * scaffolded launch.json skips. Left unskipped, js-debug loses F10 over the
+ * process's first network ask: V8's step-over of the top-level await stays a
+ * plain step, lands on js-debug's injected WebAssembly pause (undici compiling
+ * its HTTP parser for the first fetch), and js-debug resumes that pause
+ * without re-stepping, so the program runs to the end (VS Code trace,
+ * 2026-09-18). Blackboxing the dist restores the step.
+ */
+export declare const CHECKOUT_DIST_SKIP_GLOB = "**/packages/*/dist/**";
+/**
+ * Dev mode only, after linkCheckoutPackages: add CHECKOUT_DIST_SKIP_GLOB to
+ * every configuration's skipFiles in the scaffold's .vscode/launch.json.
+ * Returns true when the file changed; false when there is no launch.json, it
+ * is not plain JSON (a hand-edited one with comments is the user's), or every
+ * configuration already carries the glob.
+ */
+export declare function skipCheckoutDistInLaunch(dir: string): Promise<boolean>;
 //# sourceMappingURL=checkout.d.ts.map

package/dist/checkout.js

@@ -1,5 +1,5 @@
 import { existsSync } from "node:fs";
-import { mkdir, readFile, rm, symlink } from "node:fs/promises";
+import { mkdir, readFile, rm, symlink, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 /**
@@ -62,4 +62,51 @@ export async function linkCheckoutPackages(dir, root) {
     }
     return linked;
 }
+/**
+ * The skipFiles glob the in-repo dogfood launch configs carry. Node resolves
+ * a junction to its real path, so a linked scaffold runs the runtime from
+ * <checkout>/packages/\*\/dist — outside node_modules, which is all the
+ * scaffolded launch.json skips. Left unskipped, js-debug loses F10 over the
+ * process's first network ask: V8's step-over of the top-level await stays a
+ * plain step, lands on js-debug's injected WebAssembly pause (undici compiling
+ * its HTTP parser for the first fetch), and js-debug resumes that pause
+ * without re-stepping, so the program runs to the end (VS Code trace,
+ * 2026-09-18). Blackboxing the dist restores the step.
+ */
+export const CHECKOUT_DIST_SKIP_GLOB = "**/packages/*/dist/**";
+/**
+ * Dev mode only, after linkCheckoutPackages: add CHECKOUT_DIST_SKIP_GLOB to
+ * every configuration's skipFiles in the scaffold's .vscode/launch.json.
+ * Returns true when the file changed; false when there is no launch.json, it
+ * is not plain JSON (a hand-edited one with comments is the user's), or every
+ * configuration already carries the glob.
+ */
+export async function skipCheckoutDistInLaunch(dir) {
+    const path = join(dir, ".vscode", "launch.json");
+    if (!existsSync(path))
+        return false;
+    let launch;
+    try {
+        launch = JSON.parse(await readFile(path, "utf8"));
+    }
+    catch {
+        return false;
+    }
+    if (!Array.isArray(launch.configurations))
+        return false;
+    let changed = false;
+    for (const config of launch.configurations) {
+        if (typeof config !== "object" || config === null)
+            continue;
+        const skipFiles = Array.isArray(config.skipFiles) ? config.skipFiles : [];
+        if (skipFiles.includes(CHECKOUT_DIST_SKIP_GLOB))
+            continue;
+        config.skipFiles = [...skipFiles, CHECKOUT_DIST_SKIP_GLOB];
+        changed = true;
+    }
+    if (!changed)
+        return false;
+    await writeFile(path, `${JSON.stringify(launch, null, 2)}\n`);
+    return true;
+}
 //# sourceMappingURL=checkout.js.map