@noir-ai/create 1.13.0-beta.1 → 1.14.0-beta.1

package/dist/index.d.ts

@@ -123,8 +123,22 @@ declare function managedBlock(absPath: string, block: ManagedBlock, regionText:
  *  S-T2 relies on for a diff-free refactor. */
 declare function buildRegion(block: ManagedBlock, body: string): string;
 /** Write `content` to `absPath` only if no file exists there. Returns whether
- *  bytes were written. Parent dirs are NOT created (orchestrator's job). */
-declare function skipIfExists(absPath: string, content: string): WriteOutcome;
+ *  bytes were written. Parent dirs are created by {@link atomicWriteFile}.
+ *
+ *  `fileMode` (slice E, §8.1) is the permission for the NEWLY created file —
+ *  `0o600` for the `.noir/.env` credential seed. It is applied to the temp file
+ *  BEFORE the rename (see `AtomicWriteOptions.mode`), so the file never exists
+ *  at its final path with a laxer mode. It is deliberately ignored when the
+ *  target already exists: this writer's whole contract is "never touch an
+ *  existing file", and that includes its permissions. POSIX-only — Windows
+ *  permissions are ACL-based and the mode is dropped there.
+ *
+ *  The write goes through `atomicWriteFile` (tmp + rename) rather than a bare
+ *  `writeFileSync`: a requested mode must land on the temp, and an interrupted
+ *  seed write should not leave a half-written `.noir/.env` behind. Byte output
+ *  is unchanged for every existing caller (same content, umask default 0o644
+ *  when no mode is requested). */
+declare function skipIfExists(absPath: string, content: string, fileMode?: number): WriteOutcome;
 
 /**
  * Declarative scaffold manifest — the single source of truth for what
@@ -172,6 +186,14 @@ interface ManifestEntry {
     template?: string;
     /** One-line human description for `noir doctor` + logs. */
     description?: string;
+    /** Permission for a NEWLY created file (e.g. `0o600` for a credential seed).
+     *  Applied only on creation; an existing file's mode is never changed — the
+     *  `skipIfExists` contract means an existing file is not even opened. The
+     *  orchestrator forwards this to the writer and reports it on the result as
+     *  {@link ScaffoldResult.fileModes}. Ignored by every other write mode, whose
+     *  targets are regenerated rather than seeded.
+     *  NOTE: POSIX-only. Windows permissions are ACL-based and ignore it. */
+    fileMode?: number;
     /** Required for `mergeJson` mode: the JSON patch object (or a template that
      *  renders to one). Merged into the existing file, preserving user keys. */
     patch?: Record<string, unknown>;
@@ -232,6 +254,8 @@ declare const MANIFEST_PATH_PARITY: ReadonlyArray<[
  *    chosen host for `noir sync` to read back.)
  *  - `NOIR.md`     → managedBlock (BRIEF_BLOCK). Auto-brief is co-owned.
  *  - `RULES.md`    → skipIfExists. User-owned working-contract seed.
+ *  - `README.md`   → managedBlock (README_BLOCK). The `.noir/` runtime map is
+ *    regenerated as the layout grows; user notes outside the markers survive.
  *  - ignore files  → managedBlock (IGNORE_BLOCK). Matches syncIgnores.
  *  - host entries  → SEE {@link buildHostArtifacts} (regenerate / managedBlock).
  */
@@ -361,10 +385,10 @@ declare function mergeThreeWay(base: string, ours: string, theirs: string, style
  *    `result.conflicts` so the caller (doctor/CI) can fail loudly with a
  *    reviewable artifact rather than hang on a prompt.
  *
- * The registry ({@link MIGRATIONS}) is the deliverable at v1.0.0 — there are no
- * real version-to-version migrations yet. The synthetic `1.0.0 → 1.0.0`
- * migration exists to exercise the runner end-to-end and to give a template
- * for the first real migration.
+ * The registry ({@link MIGRATIONS}) carries two entries: the synthetic
+ * `1.0.0 → 1.0.0` smoke test that exercises the runner end-to-end, and the
+ * first real version-to-version migration, `1.0.0 → 1.1.0`. The synthetic one
+ * is the copy-pasteable template for the next contributor.
  */
 interface MigrationContext {
     /** Absolute repo root the migration operates on. */
@@ -419,6 +443,8 @@ declare function runMigrations(root: string, from: string | null, to: string, op
     ran: string[];
 };
 
+/** The registry. The runner sorts the selected window by `to`, so declaration
+ *  order is documentation only — oldest step first. */
 declare const MIGRATIONS: readonly MigrationScript[];
 /** Write git-style inline conflict markers around `theirs`/`ours` so a human
  *  or AI agent can resolve later. This is the CI-safe fallback the spec locks
@@ -467,9 +493,12 @@ interface ScaffoldOptions {
     /** Explicit project id; bypasses generate/read. Mainly for tests + `create`
      *  flows that want deterministic ids. */
     projectId?: string;
-    /** `noir init --upgrade`: run migrations before re-emitting, and emit only
-     *    regenerate + managedBlock (skipIfExists left alone). Only meaningful
-     *    with mode `'init'`. */
+    /** `noir init --upgrade`: run migrations, then re-emit every manifest mode
+     *  EXCEPT `mergeJson` (`.claude/settings.local.json` is user-owned and
+     *  write-once at init/create). `skipIfExists` keeps its
+     *  create-only-if-absent semantics, so an upgrade backfills seeds added since
+     *  initialization without ever touching a file the user owns. Only meaningful
+     *  with mode `'init'`. */
     upgrade?: boolean;
     /** SP-A: re-scaffold even when the target is already initialized (bypasses
      *    the already-initialized no-op guard). Does NOT bypass `assertSafeRoot`
@@ -535,6 +564,15 @@ interface ScaffoldResult {
      *  grepping stderr. Empty when no conflicts occurred (also on first-run +
      *  no-op). */
     conflicts: ConflictRecord[];
+    /** Permission planned for each file this run CREATED at a non-default mode
+     *  (repo-relative path → mode), i.e. the {@link ManifestEntry.fileMode} of a
+     *  `skipIfExists` entry that had no file on disk. A real run reports the mode
+     *  it applied; a `dryRun` reports the mode it WOULD apply (the predictor's
+     *  job — the caller can preview `.noir/.env` at 0600 without writing it).
+     *  Paths the entry skipped (already present) are absent: an existing file's
+     *  mode is never changed. Optional so existing external constructors of this
+     *  type (test stubs) stay valid; `scaffold()` always populates it. */
+    fileModes?: Record<string, number>;
 }
 /** One entry in {@link ScaffoldResult.conflicts}. */
 interface ConflictRecord {
@@ -614,7 +652,7 @@ declare function scaffold(opts: ScaffoldOptions): Promise<ScaffoldResult>;
  */
 /** The scaffold version this build of @noir-ai/create ships. Bumped atomically
  *  whenever a manifest entry, template, or migration changes shape. */
-declare const CURRENT_SCAFFOLD_VERSION = "1.0.0";
+declare const CURRENT_SCAFFOLD_VERSION = "1.1.0";
 /** Path to the stamp file under `root`. Exposed for tests + doctor. */
 declare function scaffoldVersionPath(root: string): string;
 /** Read the applied scaffold version, or `null` if the stamp is absent/unparseable.

package/dist/index.js

@@ -47,12 +47,15 @@ import {
   RULES_BLOCK
 } from "@noir-ai/core";
 var BRIEF_BLOCK = managedBlock("brief", "html");
+var README_BLOCK = managedBlock("readme", "html");
 var P = {
   projectId: `${NOIR_DIR}/project.id`,
   config: `${NOIR_DIR}/config.yml`,
   envExample: `${NOIR_DIR}/.env.example`,
+  env: `${NOIR_DIR}/.env`,
   noirMd: `${NOIR_DIR}/NOIR.md`,
-  rulesMd: `${NOIR_DIR}/rules/RULES.md`
+  rulesMd: `${NOIR_DIR}/rules/RULES.md`,
+  readme: `${NOIR_DIR}/README.md`
 };
 var MANIFEST_PATH_PARITY = [
   [P.projectId, paths.projectId],
@@ -82,7 +85,20 @@ function hostAgnosticEntries(ctx) {
       path: P.envExample,
       mode: "skipIfExists",
       template: "env.example.tmpl",
-      description: ".noir/.env placeholder (gitignored; copy + fill real tokens)"
+      description: ".noir/.env.example committable documentation (never loaded)"
+    },
+    {
+      // §8.1: init creates the REAL env file, not just the example. The body is
+      // all-comment, so the file parses to an EMPTY overlay and creating it
+      // changes no behaviour — it exists so the user never has to copy the
+      // example by hand. `fileMode: 0o600` because the file holds tokens the
+      // moment the user edits it (set on creation only — skipIfExists never
+      // touches an existing file, so a user's own chmod stands).
+      path: P.env,
+      mode: "skipIfExists",
+      template: "config.env.tmpl",
+      fileMode: 384,
+      description: "project-scoped env file (gitignored, 0600)"
     },
     {
       path: P.noirMd,
@@ -97,6 +113,18 @@ function hostAgnosticEntries(ctx) {
       template: "rules-seed.md.tmpl",
       description: "AI working-rules seed"
     },
+    {
+      // Slice E (spec §9): the `.noir/` runtime map — what init just wrote,
+      // what appears later (and which command creates it), and where to go
+      // next. Host-agnostic: it describes the canonical store, which every
+      // host shares. Co-owned (README_BLOCK) so user notes survive while the
+      // map stays current through `noir sync` / `init --upgrade`.
+      path: P.readme,
+      mode: "managedBlock",
+      block: README_BLOCK,
+      template: "noir-readme.md.tmpl",
+      description: ".noir/ runtime map (what exists now / what appears later)"
+    },
     // --- ignore files (host-agnostic; co-owned via IGNORE_BLOCK) ------------
     {
       path: ".gitignore",
@@ -505,7 +533,68 @@ var synthetic = {
     return result;
   }
 };
-var MIGRATIONS = [synthetic];
+var ENV_POINTER_MARKER = "# noir:env-pointer";
+var ENV_POINTER_BLOCK = [
+  ENV_POINTER_MARKER,
+  "# This file is safe to commit: it holds no secrets.",
+  "# Project-scoped values and secrets belong in .noir/.env (gitignored, mode",
+  "# 0600). .noir/.env.example documents the full variable set; `noir env`",
+  "# reports which source wins for each key.",
+  ""
+].join("\n");
+function appendSeparated(prev, block) {
+  if (prev.length === 0) return block;
+  if (prev.endsWith("\n\n")) return `${prev}${block}`;
+  return prev.endsWith("\n") ? `${prev}
+${block}` : `${prev}
+
+${block}`;
+}
+var envPointer = {
+  from: "1.0.0",
+  to: "1.1.0",
+  description: "point .noir/config.yml at .noir/.env (the secrets home)",
+  run: (ctx) => {
+    const result = { changed: [], conflicts: [], notes: [] };
+    const rel = ".noir/config.yml";
+    const abs = join3(ctx.root, ".noir", "config.yml");
+    if (!existsSync3(abs)) {
+      result.notes.push(`${rel}: absent \u2014 the template seed carries the pointer`);
+      return result;
+    }
+    let prev;
+    try {
+      prev = readFileSync2(abs, "utf8");
+    } catch (err) {
+      result.conflicts.push(rel);
+      result.notes.push(`${rel}: unreadable (${errorMessage(err)}) \u2014 left untouched`);
+      return result;
+    }
+    if (prev.includes(ENV_POINTER_MARKER)) {
+      result.notes.push(`${rel}: already carries ${ENV_POINTER_MARKER}`);
+      return result;
+    }
+    if (ctx.dryRun) {
+      result.changed.push(rel);
+      result.notes.push(`${rel}: would append the .noir/.env pointer`);
+      return result;
+    }
+    try {
+      writeFileSync2(abs, appendSeparated(prev, ENV_POINTER_BLOCK), "utf8");
+    } catch (err) {
+      result.conflicts.push(rel);
+      result.notes.push(`${rel}: write failed (${errorMessage(err)}) \u2014 left untouched`);
+      return result;
+    }
+    result.changed.push(rel);
+    result.notes.push(`${rel}: appended the .noir/.env pointer`);
+    return result;
+  }
+};
+var MIGRATIONS = [synthetic, envPointer];
+function errorMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
 function applyInlineConflict(ours, theirs, oursLabel = "ours", theirsLabel = "theirs") {
   return `<<<<<<< ${oursLabel}
 ${ours}=======
@@ -548,7 +637,7 @@ import {
   writeSync
 } from "fs";
 import { basename, dirname as dirname2, join as join4 } from "path";
-import { stripManagedBlock, writeManagedRegion } from "@noir-ai/core";
+import { atomicWriteFile, stripManagedBlock, writeManagedRegion } from "@noir-ai/core";
 function regenerate(absPath, content) {
   const dir = dirname2(absPath);
   const tmp = join4(
@@ -635,11 +724,11 @@ function predictManagedBlocks(currentContent, regions) {
 
 ${regionsJoined}` : regionsJoined;
 }
-function skipIfExists(absPath, content) {
+function skipIfExists(absPath, content, fileMode) {
   if (existsSync4(absPath)) {
     return { path: absPath, mode: "skipIfExists", written: false };
   }
-  writeFileSync3(absPath, content, "utf8");
+  atomicWriteFile(absPath, content, fileMode !== void 0 ? { mode: fileMode } : {});
   return { path: absPath, mode: "skipIfExists", written: true };
 }
 function mergeJson(absPath, patch, dedupSubstring) {
@@ -689,7 +778,7 @@ function deepMergePreservingHooks(existing, patch, dedupSubstring) {
 }
 
 // src/scaffold-version.ts
-var CURRENT_SCAFFOLD_VERSION = "1.0.0";
+var CURRENT_SCAFFOLD_VERSION = "1.1.0";
 var PREFIX = "noir-scaffold=";
 function scaffoldVersionPath(root) {
   return join5(root, NOIR_DIR2, "scaffold-version");
@@ -931,17 +1020,11 @@ function templatesDir() {
 }
 
 // src/scaffold.ts
-var WRITER_BY_MODE = {
-  // 'runtime' subset = regenerate + managedBlock (the always-safe-to-rewrite
-  // entries). sync + init --upgrade emit only this subset; skipIfExists is
-  // reserved for first-run init/create so user edits survive.
-  // 'mergeJson' (C3 SessionStart hook) is 'all' — the settings entry is
-  // written once at init/create; sync re-emits only the script + router
-  // contract (regenerate + managedBlock), never the user-owned entry.
-  regenerate: "runtime",
-  managedBlock: "runtime",
-  skipIfExists: "all",
-  mergeJson: "all"
+var EMITTED_IN = {
+  regenerate: { sync: true, upgrade: true },
+  managedBlock: { sync: true, upgrade: true },
+  skipIfExists: { sync: false, upgrade: true },
+  mergeJson: { sync: false, upgrade: false }
 };
 function assertSafeRoot(root) {
   let cur = root;
@@ -989,6 +1072,7 @@ async function scaffold(opts) {
       skipped: [],
       identical: [],
       conflicts: [],
+      fileModes: {},
       noop: true,
       migrationsRan: [],
       migrationConflicts: [],
@@ -1018,7 +1102,7 @@ async function scaffold(opts) {
     command,
     stack
   });
-  const emitRuntimeOnly = opts.mode === "sync" || opts.mode === "init" && opts.upgrade === true;
+  const emitContext = opts.mode === "sync" ? "sync" : opts.mode === "init" && opts.upgrade === true ? "upgrade" : null;
   const vars = {
     root: opts.root,
     projectId,
@@ -1030,6 +1114,7 @@ async function scaffold(opts) {
   const written = [];
   const skipped = [];
   const identical = [];
+  const fileModes = {};
   const conflictMemory = /* @__PURE__ */ new Map();
   const conflictRecords = [];
   const recordConflict = (relPath, mode, existing, proposed, resolution, similarity2) => {
@@ -1042,7 +1127,7 @@ async function scaffold(opts) {
       resolution
     });
   };
-  const groups = groupApplicableByPath(manifest, host, emitRuntimeOnly);
+  const groups = groupApplicableByPath(manifest, host, emitContext);
   for (const [relPath, entries] of groups) {
     const abs = join8(opts.root, relPath);
     const managed = entries.filter((e) => e.mode === "managedBlock");
@@ -1095,8 +1180,16 @@ async function scaffold(opts) {
     if (!opts.dryRun) mkdirSync3(dirname5(abs), { recursive: true });
     for (const entry of entries) {
       if (opts.dryRun) {
-        if (entry.mode === "skipIfExists" && existsSync6(abs)) skipped.push(entry.path);
-        else written.push(entry.path);
+        if (entry.mode === "skipIfExists") {
+          if (existsSync6(abs)) {
+            skipped.push(entry.path);
+          } else {
+            written.push(entry.path);
+            if (entry.fileMode !== void 0) fileModes[entry.path] = entry.fileMode;
+          }
+        } else {
+          written.push(entry.path);
+        }
         continue;
       }
       const body = renderEntry(entry, vars);
@@ -1156,13 +1249,17 @@ async function scaffold(opts) {
         if (out.written) written.push(entry.path);
         else identical.push(entry.path);
       } else {
-        const out = skipIfExists(abs, body);
-        if (out.written) written.push(entry.path);
-        else skipped.push(entry.path);
+        const out = skipIfExists(abs, body, entry.fileMode);
+        if (out.written) {
+          written.push(entry.path);
+          if (entry.fileMode !== void 0) fileModes[entry.path] = entry.fileMode;
+        } else {
+          skipped.push(entry.path);
+        }
       }
     }
   }
-  if ((opts.mode === "init" || opts.mode === "create") && !opts.dryRun) {
+  if ((opts.mode === "init" || opts.mode === "create") && !opts.dryRun && migrationConflicts.length === 0) {
     writeScaffoldVersion(opts.root, CURRENT_SCAFFOLD_VERSION);
   }
   if (!opts.dryRun) {
@@ -1173,6 +1270,7 @@ async function scaffold(opts) {
     skipped,
     identical,
     conflicts: conflictRecords,
+    fileModes,
     noop: false,
     migrationsRan,
     migrationConflicts,
@@ -1316,11 +1414,11 @@ function uniqueAside(abs, relPath, suffix) {
   for (let n = 1; existsSync6(candidate.abs); n++) candidate = make(`${suffix}.${n}`);
   return candidate;
 }
-function groupApplicableByPath(manifest, host, emitRuntimeOnly) {
+function groupApplicableByPath(manifest, host, emitContext) {
   const groups = /* @__PURE__ */ new Map();
   for (const entry of manifest) {
     if (entry.host !== void 0 && entry.host !== host) continue;
-    if (emitRuntimeOnly && WRITER_BY_MODE[entry.mode] !== "runtime") continue;
+    if (emitContext !== null && !EMITTED_IN[entry.mode][emitContext]) continue;
     const list = groups.get(entry.path);
     if (list) list.push(entry);
     else groups.set(entry.path, [entry]);