create-nola-lang 0.1.10 → 0.1.11

package/dist/{chunk-G2TOUJVB.js → chunk-MAULRZZD.js}

@@ -5,7 +5,7 @@ import {
 
 // src/providers.ts
 var PROVIDERS = [
-  { id: "nola", label: "Nola", hint: "25 free runs, no account or provider key needed", model: "nola.infer()" },
+  { id: "nola", label: "Nola", hint: "25 free runs, no account or provider key needed", model: '"nola"' },
   { id: "openai", label: "OpenAI", hint: 'openai("gpt-5-mini"), reads OPENAI_API_KEY', envVar: "OPENAI_API_KEY", model: 'openai("gpt-5-mini")' },
   {
     id: "anthropic",
@@ -176,6 +176,11 @@ function providerConfigUrl(provider) {
   return new URL(`../templates/_providers/${provider}.config.ts`, import.meta.url);
 }
 var RENAMES = { _gitignore: ".gitignore" };
+var GITIGNORE_URL = new URL("../templates/_gitignore", import.meta.url);
+async function withRecommendedGitignore(files) {
+  if (!files.has(".gitignore")) files.set(".gitignore", await readFile3(GITIGNORE_URL, "utf8"));
+  return files;
+}
 var SUBSTITUTED = /* @__PURE__ */ new Set(["package.json", "README.md", "main.ts"]);
 function nextStepsComment(ide, template) {
   if (ide === "vscode") {
@@ -198,11 +203,11 @@ var OFFLINE_ONLY = /* @__PURE__ */ new Set(["nola.replay.jsonl"]);
 var README_NOTES = {
   offline: {
     START_NOTE: "works offline, no API key needed",
-    PROVIDER_NOTE: "The starter 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\nyou edit `src/person.tsi` or add your own asks, switch the config to a real\nmodel (see the comment in `nola.config.ts`) and set `OPENAI_API_KEY`."
+    PROVIDER_NOTE: 'The starter 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\nyou edit `src/person.tsi` or add your own asks, switch the config to a real\nmodel (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.infer()` \u2014 platform-served inference with the trial key the\nscaffold wrote to `.env` (git-ignored). Out of runs? `npx nola-lang account` opens\nyour Nola account, where prepaid balance is added, or bring your\nown model (see the comment in `nola.config.ts`)."
+    PROVIDER_NOTE: '`nola.config.ts` sets `model: "nola"` \u2014 platform-served inference with the trial key the\nscaffold wrote to `.env` (git-ignored). Out of runs? `npx nola-lang account` opens\nyour Nola account, where prepaid balance is added, or bring your\nown model (see the comment in `nola.config.ts`).'
   }
 };
 function readmeNotes(provider) {
@@ -239,7 +244,9 @@ async function scaffold(targetDir, opts = {}) {
   const version = await ownVersion();
   if (def.source === "example") {
     const dev = await devExamplesDir();
-    const exampleFiles = dev ? await collectExampleFromDisk(dev, template) : await fetchExampleFromGitHub(template, version);
+    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 }));
     for (const [relPath, content] of exampleFiles) {
@@ -276,6 +283,10 @@ async function scaffold(targetDir, opts = {}) {
     }
   };
   await copyDir(".", ".");
+  if (!files.includes(".gitignore")) {
+    await writeFile(join3(absRoot, ".gitignore"), await readFile3(GITIGNORE_URL, "utf8"));
+    files.push(".gitignore");
+  }
   return { root, files: files.sort() };
 }
 
@@ -1286,7 +1297,7 @@ async function applyTrial(dir, init) {
   const { wrote, skipped } = await writeEnvKey(root, init.apiKey);
   wrote.push(...await ensureEnvIgnored(root));
   if (init.hasConfig) {
-    skipped.push("nola.config.ts already exists \u2014 set `model: nola.infer()` (nola from @nola-lang/runtime) to use the trial key");
+    skipped.push('nola.config.ts already exists \u2014 set `model: "nola"` to use the trial key');
   } else {
     await writeFile7(join9(root, "nola.config.ts"), await readFile8(TRIAL_CONFIG_URL, "utf8"));
     wrote.push("nola.config.ts");
@@ -1757,7 +1768,7 @@ function trialFailureNote(err) {
     reason = `too many trials from this network${wait} (${err.message})`;
   }
   return `Could not get a Nola API key: ${reason}
-The project uses its default provider instead. Retry later with \`npx nola-lang key\`, then set \`model: nola.infer()\` in nola.config.ts.`;
+The project uses its default provider instead. Retry later with \`npx nola-lang key\`, then set \`model: "nola"\` in nola.config.ts.`;
 }
 async function obtainTrial(prompter, opts, interactive) {
   try {

package/dist/flow.js

@@ -428,7 +428,7 @@ function trialFailureNote(err) {
         const wait = err.retryAfterMs !== undefined && err.retryAfterMs > 0 ? ` — try again in ${formatWait(err.retryAfterMs)}` : "";
         reason = `too many trials from this network${wait} (${err.message})`;
     }
-    return `Could not get a Nola API key: ${reason}\nThe project uses its default provider instead. Retry later with \`npx nola-lang key\`, then set \`model: nola.infer()\` in nola.config.ts.`;
+    return `Could not get a Nola API key: ${reason}\nThe project uses its default provider instead. Retry later with \`npx nola-lang key\`, then set \`model: "nola"\` in nola.config.ts.`;
 }
 /**
  * `acquireKey` for the scaffold: a failure is a note, never an exit code (the

package/dist/index.js

@@ -85,7 +85,7 @@ import {
   writeEnvKey,
   writeSession,
   writeVscodeSetup
-} from "./chunk-G2TOUJVB.js";
+} from "./chunk-MAULRZZD.js";
 import {
   clackPrompter
 } from "./chunk-7IQIRMK6.js";

package/dist/main.js

@@ -3,7 +3,7 @@ import {
   CREATE_COMMAND,
   dispatch,
   ownVersion
-} from "./chunk-G2TOUJVB.js";
+} from "./chunk-MAULRZZD.js";
 import "./chunk-FPS2V3S4.js";
 
 // src/main.ts

package/dist/providers.js

@@ -1,5 +1,5 @@
 export const PROVIDERS = [
-    { id: "nola", label: "Nola", hint: "25 free runs, no account or provider key needed", model: "nola.infer()" },
+    { id: "nola", label: "Nola", hint: "25 free runs, no account or provider key needed", model: '"nola"' },
     { id: "openai", label: "OpenAI", hint: 'openai("gpt-5-mini"), reads OPENAI_API_KEY', envVar: "OPENAI_API_KEY", model: 'openai("gpt-5-mini")' },
     {
         id: "anthropic",

package/dist/scaffold.d.ts

@@ -28,6 +28,12 @@ export interface ScaffoldOptions {
 }
 /** The config a live provider choice writes over the template's own (`templates/_providers/<id>.config.ts`). */
 export declare function providerConfigUrl(provider: Exclude<ProviderId, "none">): 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.
+ */
+export declare function withRecommendedGitignore(files: Map<string, string>): Promise<Map<string, string>>;
 /**
  * The comment that opens 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

package/dist/scaffold.js

@@ -13,6 +13,18 @@ export function providerConfigUrl(provider) {
 }
 /** _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. */
+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.
+ */
+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"]);
 /**
@@ -46,11 +58,12 @@ const README_NOTES = {
         PROVIDER_NOTE: "The starter 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 `src/person.tsi` or add your own asks, switch the config to a real\n" +
-            "model (see the comment in `nola.config.ts`) and set `OPENAI_API_KEY`.",
+            "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.infer()` — platform-served inference with the trial key the\n" +
+        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`).",
@@ -104,7 +117,7 @@ export async function scaffold(targetDir, opts = {}) {
     const version = await ownVersion();
     if (def.source === "example") {
         const dev = await devExamplesDir();
-        const exampleFiles = dev ? await collectExampleFromDisk(dev, template) : await fetchExampleFromGitHub(template, version);
+        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 }));
@@ -151,6 +164,10 @@ export async function scaffold(targetDir, opts = {}) {
         }
     };
     await copyDir(".", ".");
+    if (!files.includes(".gitignore")) {
+        await writeFile(join(absRoot, ".gitignore"), await readFile(GITIGNORE_URL, "utf8"));
+        files.push(".gitignore");
+    }
     return { root, files: files.sort() };
 }
 //# sourceMappingURL=scaffold.js.map

package/dist/trial.d.ts

@@ -1,4 +1,4 @@
-/** The canonical `model: nola.infer()` config every template gets when Nola is the chosen provider. */
+/** The canonical `model: "nola"` config every template gets when Nola is the chosen provider. */
 export declare const TRIAL_CONFIG_URL: import("url").URL;
 export declare const ENV_KEY = "NOLA_API_KEY";
 export interface TrialApplyResult {

package/dist/trial.js

@@ -1,7 +1,7 @@
 import { existsSync } from "node:fs";
 import { appendFile, readFile, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
-/** The canonical `model: nola.infer()` config every template gets when Nola is the chosen provider. */
+/** The canonical `model: "nola"` config every template gets when Nola is the chosen provider. */
 export const TRIAL_CONFIG_URL = new URL("../templates/_providers/nola.config.ts", import.meta.url);
 export const ENV_KEY = "NOLA_API_KEY";
 const IGNORE_LINES = [".env", ".env.*"];
@@ -79,7 +79,7 @@ export async function applyTrial(dir, init) {
     const { wrote, skipped } = await writeEnvKey(root, init.apiKey);
     wrote.push(...(await ensureEnvIgnored(root)));
     if (init.hasConfig) {
-        skipped.push('nola.config.ts already exists — set `model: nola.infer()` (nola from @nola-lang/runtime) to use the trial key');
+        skipped.push('nola.config.ts already exists — set `model: "nola"` to use the trial key');
     }
     else {
         await writeFile(join(root, "nola.config.ts"), await readFile(TRIAL_CONFIG_URL, "utf8"));

package/package.json

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

package/skills/nola/SKILL.md

@@ -43,7 +43,7 @@ infer function extractPerson(.text: string) {
   instruction text.
 - `ask with <modelName> <intent>` — routes one ask through a named model
   from `nola.config.ts`. The name must be a static identifier. When the
-  platform serves inference (`model: nola.infer()`) any unconfigured
+  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

package/skills/nola/references/config.md

@@ -7,8 +7,9 @@ import { defineConfig, nola, terminalTrace } from "@nola-lang/runtime";
 import { openai, mockProvider, withRetry } from "@nola-lang/providers";
 ```
 
-`defineConfig`, the `nola` namespace (`nola.infer()`, `nola.tracer()`),
-`terminalTrace()` and everything app-facing come from `@nola-lang/runtime`.
+`defineConfig`, the `nola` namespace (`nola.infer()`, `nola.tracer()` —
+import it ONLY when you need their options; the plain cases are the strings
+`model: "nola"` and `telemetry: "<url>"`), `terminalTrace()` and everything app-facing come from `@nola-lang/runtime`.
 Everything bring-your-own — vendor factories (`openai`, `anthropic`,
 `google`, `typesafe`, `mockProvider`), resilience combinators (`withRetry`, `fallback`,
 `roundRobin`, `constant`, `exponential`) and record/replay (`record`,
@@ -48,15 +49,22 @@ fails definitively before the network on anything else. Use it behind
 escalate to a general model. Never scaffold it as the only model.
 
 `nola` is a NAMESPACE, not a function (`nola({})` is a type error).
-`nola.infer()` is the platform model — the Nola platform (api.nola.sh, or a
-self-hosted console at `baseUrl`) serves inference and reads `NOLA_API_KEY`;
-with no argument the platform picks the model:
+The platform model is written as the STRING `"nola"` — the Nola platform
+(api.nola.sh) serves inference, reads `NOLA_API_KEY`, and picks the model.
+PREFER this form; it is what the scaffolder writes and it needs no `nola`
+import:
 
 ```ts
-import { defineConfig, nola } from "@nola-lang/runtime";
-export default defineConfig({ model: nola.infer() });
+import { defineConfig } from "@nola-lang/runtime";
+export default defineConfig({ model: "nola" });
 ```
 
+`"nola"` is short for `nola.infer()`. It is the ONLY string the `model` slot
+takes (any other string is NOLA3003 — `model: "gpt-5"` is not a thing) and
+it works as the map's `default` too. Write the `nola.infer(...)` call only
+when you need an argument — the upstream selector or the connection options
+(a self-hosted console at `baseUrl`, a key source, `retry`).
+
 When the platform serves, `ask with <name>` accepts ANY name — a configured
 map key pins that model as usual, and any other name (`fast`, `careful`, …)
 is sent with the request as a free-form inference profile that the
@@ -65,9 +73,9 @@ temperature/topK tuning). A local model map keeps strict name validation
 (unknown names are NOLA3004). `nola.infer("<provider>/<model>")` names the
 upstream explicitly; `nola.infer({ baseUrl, apiKey, apiKeyEnv, retry, model })`
 carries the connection. Beside your own models it is the map's `default`:
-`model: { default: nola.infer(), fast: openai("gpt-5-nano") }`. Nothing else
-is implied — traces go to the platform only when `telemetry` lists
-`nola.tracer()`.
+`model: { default: "nola", fast: openai("gpt-5-nano") }`. Nothing else
+is implied — traces go to a Nola console only when `telemetry` lists its
+URL (or `nola.tracer()`).
 
 `npm create nola` asks *Select an inference provider:* right after the
 template — Nola (25 free runs) first, then OpenAI / Anthropic / Gemini, then
@@ -114,7 +122,7 @@ export infer function summarize(.text: string) {
 
 An `ask with` name that is not a key of the map fails at run time with
 NOLA3004, listing the configured names — EXCEPT when `default` is
-`nola.infer()`, where the unmatched name becomes an inference profile for
+the platform model (`"nola"`), where the unmatched name becomes an inference profile for
 the platform instead of an error.
 
 ### Other config sections
@@ -146,14 +154,19 @@ event at `debug`, coloured on a TTY, written to STDERR — stdout stays the
 program's), ONE observer, or an ARRAY of
 observers. An observer or an array REPLACES the terminal — nothing is
 implied, so list `terminalTrace()` to keep it; `[]` is silent. Observers:
-`nola.tracer()` / `nola.tracer("http://localhost:4141")` /
-`nola.tracer({ baseUrl, apiKey? })` (posts to a Nola-Protocol server;
-keyless on loopback; never gated — listed means sends), `terminalTrace({
+an `http(s)` URL STRING — the tracer, PREFER this form (`telemetry:
+"http://127.0.0.1:4141"`, or as an array entry; posts to a Nola-Protocol
+server such as `npx nola-lang console`; keyless on loopback; never gated —
+listed means sends; a single URL replaces the terminal like any single
+observer, so write `["http://127.0.0.1:4141", terminalTrace()]` to keep
+both; a non-URL string is NOLA3003), the call behind it for its options —
+`nola.tracer()` (default target) / `nola.tracer({ baseUrl, apiKey? })` —
+`terminalTrace({
 level })`, or any object with on* methods (`onAskStart`,
 `onProviderRequest`, `onProviderResponse`, `onValidationFailed`, `onRetry`,
 `onAskEnd`, `onInvocationStart`, `onInvocationEnd`; that shape is
-`NolaTelemetry`). The global `console` is NOT an entry. `nola.infer()` does
-NOT imply a tracer. `NOLA_TRACING_URL` appends `nola.tracer(url)`; a config
+`NolaTelemetry`). The global `console` is NOT an entry. `model: "nola"` does
+NOT imply a tracer. `NOLA_TRACING_URL` appends that URL's tracer; a config
 that lists a tracer itself wins, with a notice. Sending is fire-and-forget
 and never affects inference. The platform model is root-only: it cannot
 appear inside combinators or non-default map entries. Start the local
@@ -210,11 +223,11 @@ the providers package:
     "check": "nola check"
   },
   "dependencies": {
-    "@nola-lang/providers": "^0.1.10",
-    "@nola-lang/runtime": "^0.1.10"
+    "@nola-lang/providers": "^0.1.11",
+    "@nola-lang/runtime": "^0.1.11"
   },
   "devDependencies": {
-    "nola-lang": "^0.1.10",
+    "nola-lang": "^0.1.11",
     "typescript": "^5.6.0"
   },
   "engines": { "node": ">=22.18" }

package/skills/nola/references/syntax.md

@@ -201,7 +201,7 @@ export infer function summarize(.text: string) {
   use `.withModel(...)` for a dynamic model.
 - The name is matched against the config at ask time, not compile time. A
   name that matches a `model` map key pins that model. When the platform
-  serves inference (`model: nola.infer()`) an unmatched name is a
+  serves inference (`model: "nola"`) an unmatched name is a
   free-form inference profile sent to the platform — not an error; under a
   local default an unknown name is a runtime `NolaConfigError` (NOLA3004).
 - `ask without` is a plain ask of the identifier `without`, not a pin.

package/templates/_gitignore

@@ -0,0 +1,10 @@
+node_modules/
+dist/
+*.tsbuildinfo
+
+# `nola declarations` / bundler-plugin output — generated next to sources
+*.d.tsi.ts
+
+.env
+.env.*
+!.env.example

package/templates/_providers/nola.config.ts

@@ -1,4 +1,4 @@
-import { defineConfig, nola } from "@nola-lang/runtime";
+import { defineConfig } from "@nola-lang/runtime";
 
 // Nola serves inference: reads NOLA_API_KEY from .env (your free trial key)
 // and picks the model. Out of runs? `npx nola-lang account` opens your Nola
@@ -7,5 +7,5 @@ import { defineConfig, nola } from "@nola-lang/runtime";
 //   import { openai } from "@nola-lang/providers";
 //   model: openai("gpt-5-mini"),   // reads OPENAI_API_KEY
 export default defineConfig({
-  model: nola.infer(),
+  model: "nola",
 });

package/templates/starter/nola.config.ts

@@ -6,6 +6,8 @@ export default defineConfig({
   // (nola.replay.jsonl), so the first `npm start` needs no API key. The
   // ledger is keyed by the exact prompt — once you edit the .tsi or add
   // asks, switch to a real model:
+  //   model: "nola",                 // Nola serves inference; `npx nola-lang key` writes NOLA_API_KEY (25 free runs)
+  // or bring your own:
   //   import { openai } from "@nola-lang/providers";
   //   model: openai("gpt-5-mini"),   // reads OPENAI_API_KEY
   model: replay("./nola.replay.jsonl"),

package/templates/empty/_gitignore

@@ -1,5 +0,0 @@
-node_modules/
-dist/
-
-.env
-.env.*

package/templates/starter/_gitignore

@@ -1,5 +0,0 @@
-node_modules/
-dist/
-
-.env
-.env.*