create-nola-lang 0.1.13 → 0.1.14

package/dist/scaffold.d.ts

@@ -13,16 +13,14 @@ export interface ScaffoldOptions {
     /**
      * The inference provider chosen in the wizard; default "none" (the
      * template's own config). Any live provider replaces `nola.config.ts` with
-     * that provider's config, skips the offline templates' replay ledger, and renders
-     * the matching README notes.
+     * that provider's config and drops the offline templates' replay ledger.
      */
     provider?: ProviderId;
     /**
      * The editor chosen in the wizard; default "none". Decides the next-steps
-     * comment rendered at the top of the template's src/main.ts: with VS Code
-     * it names F5, breakpoints and the recommended extension (all of which the
-     * .vscode files the flow writes make true); without one it stays
-     * editor-neutral.
+     * comment that opens the template's entry file: with VS Code it names F5,
+     * breakpoints and the recommended extension (all of which the .vscode
+     * files the flow writes make true); without one it stays editor-neutral.
      */
     ide?: "vscode" | "none";
 }
@@ -42,23 +40,29 @@ export declare function vendorEnvVar(template: string, provider: ProviderId): st
  */
 export declare function envExample(envVar: string): string;
 /**
- * Add the recommended `.gitignore` to an example's files. Examples are copied
- * verbatim from `examples/`, where the monorepo's root ignore file covers them,
- * so they carry none — one an example does carry wins.
+ * Add the recommended `.gitignore` to a template's files. Templates are
+ * copied as committed — examples from `examples/`, where the monorepo's root
+ * ignore file covers them — so they carry none; one a template does carry wins.
  */
 export declare function withRecommendedGitignore(files: Map<string, string>): Promise<Map<string, string>>;
 /**
- * The comment that opens the entry file (src/main.ts, or the `.tsi` entry
- * of a one-file template) — the file the scaffold lands the user on (VS Code opens it
- * as the active editor), so it carries the first three things to do. The VS
- * Code variant only ships with the editor step's .vscode files, which are
- * what make F5 and the extension prompt real.
+ * The comment that opens the entry file (the `.tsi` entry of a one-file
+ * template and of `empty`, else the plain-TS src/main.ts) — the file the
+ * scaffold lands the user on (VS Code opens it as the active editor), so it
+ * carries the first three things to do. The VS Code variant only ships with
+ * the editor step's .vscode files, which are what make F5 and the extension
+ * prompt real.
  */
 export declare function nextStepsComment(ide: "vscode" | "none", template: string): string;
 export declare function ownVersion(): Promise<string>;
 /**
  * Lay a template down into `targetDir`. One implementation serves both entry
- * points: the `create-nola-lang` bin (`npm create nola-lang`) and `nola init`.
+ * points — the `create-nola-lang` bin (`npm create nola-lang`) and `nola init`
+ * — and both sources: the files are collected as committed, then the scaffold
+ * adds what a project needs on top — the chosen provider's config (dropping
+ * the replay ledger), the project name and the lockstep ranges in
+ * package.json, the recommended .gitignore, the vendor key's .env.example,
+ * and the next-steps comment at the top of the entry file.
  */
 export declare function scaffold(targetDir: string, opts?: ScaffoldOptions): Promise<ScaffoldResult>;
 //# sourceMappingURL=scaffold.d.ts.map

package/dist/scaffold.js

@@ -5,7 +5,8 @@ import { fileURLToPath } from "node:url";
 import { collectExampleFromDisk, devExamplesDir, rewriteExamplePackageJson } from "./examples.js";
 import { fetchExampleFromGitHub } from "./github.js";
 import { providerById } from "./providers.js";
-import { templateByName, templateNames } from "./registry.js";
+import { entryFile, templateByName, templateNames } from "./registry.js";
+/** This package's own templates: `empty` (the one builtin), `_providers/` and `_gitignore`. */
 const TEMPLATES_DIR = fileURLToPath(new URL("../templates/", import.meta.url));
 /** The config a live provider choice writes over the template's own (`templates/_providers/<id>.config.ts`). */
 export function providerConfigUrl(provider) {
@@ -28,36 +29,36 @@ export function vendorEnvVar(template, provider) {
 export function envExample(envVar) {
     return `# Copy to .env and fill in — \`nola run\` applies .env before evaluating nola.config.ts.\n${envVar}=\n`;
 }
-/** _gitignore ships underscored (npm pack strips nested .gitignore files). */
-const RENAMES = { _gitignore: ".gitignore" };
-/** The ONE recommended .gitignore — every scaffold gets it; no template keeps a copy of its own. */
+/** The ONE recommended .gitignore — every scaffold gets it; no template keeps a copy of its own (_gitignore ships underscored: npm pack strips nested .gitignore files). */
 const GITIGNORE_URL = new URL("../templates/_gitignore", import.meta.url);
 /**
- * Add the recommended `.gitignore` to an example's files. Examples are copied
- * verbatim from `examples/`, where the monorepo's root ignore file covers them,
- * so they carry none — one an example does carry wins.
+ * Add the recommended `.gitignore` to a template's files. Templates are
+ * copied as committed — examples from `examples/`, where the monorepo's root
+ * ignore file covers them — so they carry none; one a template does carry wins.
  */
 export async function withRecommendedGitignore(files) {
     if (!files.has(".gitignore"))
         files.set(".gitignore", await readFile(GITIGNORE_URL, "utf8"));
     return files;
 }
-/** Files whose __NAME__/__VERSION__, README-note and __NEXT_STEPS__ placeholders are substituted. */
-const SUBSTITUTED = new Set(["package.json", "README.md", "main.ts", "main.tsi"]);
 /**
- * The comment that opens the entry file (src/main.ts, or the `.tsi` entry
- * of a one-file template) — the file the scaffold lands the user on (VS Code opens it
- * as the active editor), so it carries the first three things to do. The VS
- * Code variant only ships with the editor step's .vscode files, which are
- * what make F5 and the extension prompt real.
+ * The comment that opens the entry file (the `.tsi` entry of a one-file
+ * template and of `empty`, else the plain-TS src/main.ts) — the file the
+ * scaffold lands the user on (VS Code opens it as the active editor), so it
+ * carries the first three things to do. The VS Code variant only ships with
+ * the editor step's .vscode files, which are what make F5 and the extension
+ * prompt real.
  */
 export function nextStepsComment(ide, template) {
     if (ide === "vscode") {
-        const breakpointIn = templateByName(template)?.entry
-            ? "on the `ask` line below"
-            : template === "typescript-interop"
-                ? "in src/person.tsi"
-                : "in your .tsi file";
+        // `empty`'s stub has no ask yet — the breakpoint goes on the one the user writes.
+        const breakpointIn = template === "empty"
+            ? "on your first `ask` in this file"
+            : templateByName(template)?.entry
+                ? "on the `ask` line below"
+                : template === "typescript-interop"
+                    ? "in src/person.tsi"
+                    : "in your .tsi file";
         return [
             "// Next steps in VS Code:",
             "//   1. Press F5 to run this file (.vscode/launch.json is already set up).",
@@ -73,40 +74,7 @@ export function nextStepsComment(ide, template) {
     ].join("\n");
 }
 /** Template files that only make sense for the offline (replay) configuration. */
-const OFFLINE_ONLY = new Set(["nola.replay.jsonl"]);
-const README_NOTES = {
-    offline: {
-        START_NOTE: "works offline, no API key needed",
-        PROVIDER_NOTE: "This project runs offline: `nola.config.ts` replays answers from the committed\n" +
-            "`nola.replay.jsonl` ledger. The ledger is keyed by the exact prompt, so once\n" +
-            "you edit the `.tsi` file or add your own asks, switch the config to a real\n" +
-            "model (see the comment in `nola.config.ts`): `model: \"nola\"` with a key from\n" +
-            "`npx nola-lang key` (25 free runs), or your own provider and its key.",
-    },
-    nola: {
-        START_NOTE: "uses your 25 free Nola runs (key in .env)",
-        PROVIDER_NOTE: "`nola.config.ts` sets `model: \"nola\"` — platform-served inference with the trial key the\n" +
-            "scaffold wrote to `.env` (git-ignored). Out of runs? `npx nola-lang account` opens\n" +
-            "your Nola account, where prepaid balance is added, or bring your\n" +
-            "own model (see the comment in `nola.config.ts`).",
-    },
-};
-/** The README notes for a chosen provider: offline, the Nola trial, or a vendor and the env var its factory reads. */
-function readmeNotes(provider) {
-    if (provider === "none")
-        return README_NOTES.offline;
-    if (provider === "nola")
-        return README_NOTES.nola;
-    const def = providerById(provider);
-    if (!def?.envVar || !def.model)
-        throw new Error(`provider "${provider}" has no vendor config`);
-    return {
-        START_NOTE: `set ${def.envVar} in .env first`,
-        PROVIDER_NOTE: `\`nola.config.ts\` sets \`model: ${def.model}\` — ${def.label} serves inference with the key it reads\n` +
-            `from \`${def.envVar}\`. Copy \`.env.example\` to \`.env\` (git-ignored; \`nola run\` applies it) and fill in\n` +
-            `\`${def.envVar}\` before the first \`npm start\`, or switch models in \`nola.config.ts\`.`,
-    };
-}
+const OFFLINE_ONLY = ["nola.replay.jsonl"];
 export async function ownVersion() {
     const pkg = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
     return pkg.version;
@@ -123,9 +91,26 @@ async function prepareTarget(absRoot, force) {
     for (const entry of entries)
         await rm(join(absRoot, entry), { recursive: true, force: true });
 }
+/**
+ * A template's files as committed: `empty` from this package's templates/
+ * dir, every other template from examples/ — the dev checkout's on disk,
+ * else GitHub at the lockstep tag. Everything is buffered before the caller
+ * touches the target, so a failed fetch scaffolds nothing.
+ */
+async function collectTemplate(def, version) {
+    if (def.source === "builtin")
+        return collectExampleFromDisk(TEMPLATES_DIR, def.name);
+    const dev = await devExamplesDir();
+    return dev ? collectExampleFromDisk(dev, def.name) : fetchExampleFromGitHub(def.name, version);
+}
 /**
  * Lay a template down into `targetDir`. One implementation serves both entry
- * points: the `create-nola-lang` bin (`npm create nola-lang`) and `nola init`.
+ * points — the `create-nola-lang` bin (`npm create nola-lang`) and `nola init`
+ * — and both sources: the files are collected as committed, then the scaffold
+ * adds what a project needs on top — the chosen provider's config (dropping
+ * the replay ledger), the project name and the lockstep ranges in
+ * package.json, the recommended .gitignore, the vendor key's .env.example,
+ * and the next-steps comment at the top of the entry file.
  */
 export async function scaffold(targetDir, opts = {}) {
     const root = targetDir;
@@ -134,69 +119,34 @@ export async function scaffold(targetDir, opts = {}) {
     const def = templateByName(template);
     if (!def)
         throw new Error(`unknown template "${template}" (valid: ${templateNames().join(", ")})`);
+    const version = await ownVersion();
+    const files = await collectTemplate(def, version);
     await prepareTarget(absRoot, opts.force ?? false);
     const name = opts.name ?? basename(absRoot);
-    const version = await ownVersion();
-    const envVar = vendorEnvVar(template, opts.provider ?? "none");
-    if (def.source === "example") {
-        const dev = await devExamplesDir();
-        const exampleFiles = await withRecommendedGitignore(dev ? await collectExampleFromDisk(dev, template) : await fetchExampleFromGitHub(template, version));
-        const manifest = exampleFiles.get("package.json");
-        if (manifest)
-            exampleFiles.set("package.json", rewriteExamplePackageJson(manifest, { name, version }));
-        if (envVar !== undefined && !exampleFiles.has(".env.example"))
-            exampleFiles.set(".env.example", envExample(envVar));
-        for (const [relPath, content] of exampleFiles) {
-            const target = join(absRoot, relPath);
-            await mkdir(join(target, ".."), { recursive: true });
-            await writeFile(target, content);
-        }
-        return { root, files: [...exampleFiles.keys()].sort() };
-    }
-    const templateRoot = join(TEMPLATES_DIR, template);
-    const versionRange = `^${version}`;
     const provider = opts.provider ?? "none";
-    const notes = readmeNotes(provider);
-    const nextSteps = nextStepsComment(opts.ide ?? "none", template);
-    const files = [];
-    const copyDir = async (fromDir, relDir) => {
-        await mkdir(join(absRoot, relDir), { recursive: true });
-        for (const entry of await readdir(join(templateRoot, fromDir), { withFileTypes: true })) {
-            const fromRel = join(fromDir, entry.name);
-            if (entry.isDirectory()) {
-                await copyDir(fromRel, join(relDir, entry.name));
-                continue;
-            }
-            const toName = RENAMES[entry.name] ?? entry.name;
-            if (provider !== "none" && OFFLINE_ONLY.has(entry.name))
-                continue;
-            const toRel = join(relDir, toName);
-            // A live provider's config replaces the template's own (both builtin templates keep it at the root).
-            const source = provider !== "none" && relDir === "." && entry.name === "nola.config.ts"
-                ? providerConfigUrl(provider)
-                : join(templateRoot, fromRel);
-            let content = await readFile(source, "utf8");
-            if (SUBSTITUTED.has(entry.name)) {
-                content = content
-                    .replaceAll("__NAME__", name)
-                    .replaceAll("__VERSION__", versionRange)
-                    .replaceAll("__START_NOTE__", notes.START_NOTE)
-                    .replaceAll("__PROVIDER_NOTE__", notes.PROVIDER_NOTE)
-                    .replaceAll("__NEXT_STEPS__", nextSteps);
-            }
-            await writeFile(join(absRoot, toRel), content);
-            files.push(toRel.replaceAll("\\", "/"));
-        }
-    };
-    await copyDir(".", ".");
-    if (!files.includes(".gitignore")) {
-        await writeFile(join(absRoot, ".gitignore"), await readFile(GITIGNORE_URL, "utf8"));
-        files.push(".gitignore");
+    // A live provider's config replaces the template's own; the ledger it replayed goes with it.
+    if (provider !== "none") {
+        for (const offline of OFFLINE_ONLY)
+            files.delete(offline);
+        files.set("nola.config.ts", await readFile(providerConfigUrl(provider), "utf8"));
     }
-    if (envVar !== undefined) {
-        await writeFile(join(absRoot, ".env.example"), envExample(envVar));
-        files.push(".env.example");
+    const manifest = files.get("package.json");
+    if (manifest)
+        files.set("package.json", rewriteExamplePackageJson(manifest, { name, version }));
+    await withRecommendedGitignore(files);
+    const envVar = vendorEnvVar(template, provider);
+    if (envVar !== undefined && !files.has(".env.example"))
+        files.set(".env.example", envExample(envVar));
+    // The entry file greets the user with the next steps — it is what VS Code opens.
+    const entry = entryFile(template);
+    const program = files.get(entry);
+    if (program !== undefined)
+        files.set(entry, `${nextStepsComment(opts.ide ?? "none", template)}\n\n${program}`);
+    for (const [relPath, content] of files) {
+        const target = join(absRoot, relPath);
+        await mkdir(join(target, ".."), { recursive: true });
+        await writeFile(target, content);
     }
-    return { root, files: files.sort() };
+    return { root, files: [...files.keys()].sort() };
 }
 //# sourceMappingURL=scaffold.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-nola-lang",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "description": "Scaffold a new Nola project (npm create nola, or npm create nola-lang)",
   "keywords": [
     "nola",

package/skills/nola/SKILL.md

@@ -22,24 +22,39 @@ import type { Person } from "./types.js";
 // thenable Intent<T>. `await`ing it (or `ask`) runs the inference.
 infer function extractPerson(.text: string) {
   // `ask` resolves an intent the way `await` resolves a promise.
-  const person = ask `Extract the person described in the text`<Person>;
+  const person = ask `Extract the person described in the text`: Person;
   return person;
 }
 ```
 
-- `infer function name(...)` — declares a nola function. An optional
-  backtick instruction goes between name and params:
-  `` infer function name`instruction`(...) ``. `await` is legal in the body.
+- `infer function name(...)` — declares a nola function. Any bare template
+  literal on its own line in the body is a CONTEXT STATEMENT: text every
+  later `ask` in the invocation sees, read at each ask. It may continue with
+  values: `` `Page` oncall `when the ticket is an outage.` `` (a name, a call
+  or a bracketed literal; anything else in parentheses — but `await`, `ask`
+  and `this` cannot be values: assign them to a local first). Several are
+  legal, anywhere in the body; one before a loop shows the current state on
+  every pass. Visibility is lexical, like a `const`: a statement inside a
+  block reaches only the asks inside those braces, and statements never
+  accumulate across loop passes — each ask sees every statement visible at
+  its position exactly once, rendered at that ask. `await` is legal in the
+  body.
 - `.name: T` parameters are CONTEXT parameters: their values are shown to
   the LLM. Plain (no dot) parameters are ordinary values the LLM never
   sees. `.` is only legal on infer-function parameters. Rule of thumb:
   one dot marks a value flowing INTO the model (`.name`); a template after
   `ask` is a value coming OUT.
-- `` ask `prompt`<T> `` — an extractor: asks the LLM for a `T`.
-  `${...}` interpolation works inside the backticks. Anywhere that is NOT
-  directly after `ask` — a stored intent, a call-intent argument, an
-  object/array literal — spell it `` ..`prompt`<T> `` (a typed template
-  there without the dots is NOLA2014); `` ask ..`prompt` `` is still legal.
+- `` ask `prompt`: T `` — an extractor: asks the LLM for a `T`. The colon
+  is glued to the closing backtick; `` ask `prompt`<T> `` is the same
+  construct (write `: T` unless a page shows otherwise).
+  `${...}` interpolation works inside the backticks. The `..` is implied
+  directly after `ask` and in a call's argument list — a typed template
+  that starts an argument, or a value nested in a plain object/array
+  literal there, is an extractor: `` createTicket(`a short title`: string, 2) ``.
+  Anywhere else — a stored intent, a ternary, a spread, `new` — spell it
+  `` ..`prompt`: T `` (a typed `` `x`<T> `` elsewhere is NOLA2014, a
+  `` `x`: T `` a syntax error); `` ask ..`prompt` `` and `` fn(..`x`: T) ``
+  are still legal.
 - `` ask fn`hint`(...) `` — or a plain call whose arguments contain an
   extractor — is a call intent (the LLM fills the extractor-shaped
   arguments, then the function runs). Only `` fn`hint`(...) `` carries
@@ -48,12 +63,29 @@ infer function extractPerson(.text: string) {
   from `nola.config.ts`. The name must be a static identifier. When the
   platform serves inference (`model: "nola"`) any unconfigured
   name is legal — it is sent to the platform as a free-form inference profile.
-- Prompt templates: inside ANY instruction backticks (marker, extractor,
-  call hint) a hole that starts with a single dot — `${.member}` — reads
-  the intent's prompt scope; a literal containing one REPLACES that
-  intent's prompt block (`${.default}` is the built-in block, `${.next}`
-  the rest of the prompt). Every other `${expr}` is a lexical value.
-  See `references/syntax.md` → "Prompt templates".
+- Values in an instruction — two spellings, one rule: `.name` (a contextual
+  parameter or `const .name` binding) is DATA, rendered as an `<input
+  name>` block the system turn marks as data; a value after text in a
+  context statement (`` `Page` oncall ``) or a `${expr}` hole in ANY
+  instruction backticks is part of the developer's words, spliced where it
+  stands (a string verbatim, a function its name, a call intent its callee
+  and arguments, anything else JSON) — the model FOLLOWS it, so interpolate
+  only text the developer controls (a team name, a count, a date) and put
+  anything a user or a document supplied in `.name`. A context statement is
+  read at EACH ask that sees it (module or body alike); an extractor's or
+  hint's text when the ask runs. A Nola construct (`ask`, `..`) inside a
+  context statement's value or hole, or in a call hint's hole, is NOLA2010
+  (written bare right after the text, NOLA1020); a call intent is a legal
+  value (a HINTED `` fn`hint`(…) `` one only in parentheses or a `${}` hole —
+  bare it is no call intent, and its extractor argument is NOLA2010). There
+  is no `${.member}` prompt scope (a dot cannot start a hole's expression).
+  See `references/syntax.md` → "Context statements" and "Values in an
+  instruction".
+- The prompt itself is the developer's words in four tags — `<context
+  function|module>` with `<input name>` blocks, then `<task>` (`<task
+  call="fn">` for a call intent); the schema rides structured output, never
+  the prompt; `system.message` REPLACES the default system text. See
+  `references/syntax.md` → "The prompt".
 
 ## Where Nola diverges from TypeScript — hard rules
 
@@ -72,7 +104,7 @@ infer function extractPerson(.text: string) {
   with an exported type's name (NOLA2011). `./x.tsi` with no `x.tsi` on disk
   is the VIEW of `x.ts`: the same module plus those values — import plain-TS
   types that way when you need their schema. Keep one basename per module.
-- An extractor's `<T>` should be a named, JSON-shaped type. The schema comes
+- An extractor's type should be a named, JSON-shaped type. The schema comes
   from the RESOLVED type, so unions (a `kind` key makes them discriminated),
   `Partial<T>`, `extends`, `Record<string, T>` and types from packages all
   work; `Date` is revived to a real `Date`. `Map`/`Set`/`Promise`, functions

package/skills/nola/references/config.md

@@ -124,8 +124,8 @@ export default defineConfig({
 
 ```tsi
 export infer function summarize(.text: string) {
-  const draft = ask with fast `a rough summary`<string>;
-  return ask with careful `a polished summary of: ${draft}`<string>;
+  const draft = ask with fast `a rough summary`: string;
+  return ask with careful `a polished summary of: ${draft}`: string;
 }
 ```
 
@@ -232,11 +232,11 @@ the providers package:
     "check": "nola check"
   },
   "dependencies": {
-    "@nola-lang/providers": "^0.1.13",
-    "@nola-lang/runtime": "^0.1.13"
+    "@nola-lang/providers": "^0.1.14",
+    "@nola-lang/runtime": "^0.1.14"
   },
   "devDependencies": {
-    "nola-lang": "^0.1.13",
+    "nola-lang": "^0.1.14",
     "typescript": "^5.6.0"
   },
   "engines": { "node": ">=22.18" }