@noir-ai/create 1.15.0 → 1.16.0-beta.1

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { HostId, HostAdapter } from '@noir-ai/adapters';
-import { ManagedBlock } from '@noir-ai/core';
+import { FileModeOutcome, ManagedBlock } from '@noir-ai/core';
+export { ensureOwnerOnly } from '@noir-ai/core';
 
 /** Absolute path of the ancestor store under `root`. */
 declare function ancestorsPath(root: string): string;
@@ -70,7 +71,6 @@ declare function detectStack(root: string): StackInfo;
  * file may be refreshed during an upgrade.
  *
  * WHY THIS EXISTS
- * ---------------
  * `noir init` writes two files whose only job is to be read by a human:
  * `.noir/.env.example` (documents the variable set) and `.noir/rules/RULES.md`
  * (the AI working-contract seed). Both are emitted create-only-if-absent, and
@@ -92,7 +92,6 @@ declare function detectStack(root: string): StackInfo;
  * leftover and refreshing it loses nothing.
  *
  * THE CONTRACT
- * ------------
  * {@link isStaleSeed} answers exactly that question. It is deliberately
  * conservative in one direction: it returns `true` only on an exact match
  * against a recorded past version, so ANY other byte difference — a user edit,
@@ -109,7 +108,6 @@ declare function detectStack(root: string): StackInfo;
  * file it just read; the argument makes it say so.
  *
  * RENDERING
- * ---------
  * Seed templates are normally interpolated through `render(template, vars)`
  * before writing. That step is a no-op for the two templates recorded here:
  * neither contains a `{{...}}` token, so `render(text, vars) === text` for
@@ -126,7 +124,6 @@ declare function detectStack(root: string): StackInfo;
  * requirement impossible to overlook.
  *
  * APPENDING TO THE HISTORY
- * ------------------------
  * Record the template bytes as they shipped, keyed by the scaffold version
  * whose `init` wrote them, and never edit an existing entry — a user's disk
  * still holds those old bytes, and rewriting history would silently reclassify
@@ -276,8 +273,15 @@ declare function buildRegion(block: ManagedBlock, body: string): string;
  *  `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). */
+ *  when no mode is requested).
+ *
+ *  An EXISTING file keeps this writer's create-only contract, but its mode is
+ *  not left to drift: the orchestrator calls {@link ensureOwnerOnly} after the
+ *  emit, which tightens a group/world-readable credential to 0600. */
 declare function skipIfExists(absPath: string, content: string, fileMode?: number): WriteOutcome;
+/** What happened when the owner-only mode was re-asserted on a credential
+ *  file — see {@link ensureOwnerOnly}. */
+type EnvMode = FileModeOutcome;
 
 /**
  * Declarative scaffold manifest — the single source of truth for what
@@ -348,11 +352,12 @@ interface ManifestEntry {
     /** 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.
+     *  Applied only on creation — 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}; the mode of
+     *  an existing credential file is re-asserted separately (`ensureOwnerOnly`).
+     *  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
@@ -385,6 +390,14 @@ type BuildManifestContext = {
      *  .prettierignore only for JS; .dockerignore only when a Dockerfile is
      *  present; an unknown/empty stack ⇒ all four, for backward compat). */
     stack?: StackInfo;
+    /** The `rules.enabled` switch from the project's `.noir/config.yml`. False
+     *  drops the working-rules seed from the manifest, so no command emits or
+     *  backfills `.noir/rules/RULES.md` for a project that opted out. Undefined
+     *  (the schema's default state, and every caller that predates the switch)
+     *  means enabled — a project with no `rules:` block emits the seed exactly
+     *  as before. A file already on disk is never removed: dropping the entry
+     *  removes the emission, not the file. */
+    rulesEnabled?: boolean;
 };
 /** Co-owned NOIR.md auto-brief region. Defined locally (not exported from
  *  core) because core's own named block instances cover only the three
@@ -433,6 +446,12 @@ interface BuildHostArtifactsContext {
      *  native install is detected, else `'noir'`). Passed through to
      *  `adapter.emitMcpConfig`. */
     command: string;
+    /** The project's `rules.enabled` switch. False drops the rules `@`-import a
+     *  host would otherwise emit (CLAUDE.md's rules block, GEMINI.md's rules
+     *  block, AGENTS.md's rules import) so no host file points at a
+     *  `.noir/rules/RULES.md` that the switch withheld. Undefined means enabled —
+     *  byte-identical to every build that predates the switch. */
+    rulesEnabled?: boolean;
 }
 /**
  * Materialize the host-specific manifest entries from a resolved adapter.
@@ -466,12 +485,22 @@ interface BuildHostArtifactsContext {
  *      collided with the cursor flat-skill prune of `noir-*.mdc` under
  *      `.cursor/rules/`, and cursor's rules are already delivered via
  *      AGENTS.md's `@.noir/rules/RULES.md` import.)
+ *
+ *      That rules import/block is dropped for every host when
+ *      `ctx.rulesEnabled` is false: the switch withholds the seed, so pointing
+ *      a host at it would resolve to nothing. The context import is unaffected
+ *      — the switch gates the rules, not the brief. A host file that already
+ *      carries the rules region from when the switch was on keeps it: dropping
+ *      the entry stops the emission, and nothing here rewrites a region out of
+ *      an existing file.
  *   3. **Host MCP config** — `regenerate` at `adapter.mcpConfigPath(ctx)`
  *      (default `<root>/.mcp.json` for claude), content from
  *      `adapter.emitMcpConfig(ctx, {transport,url})`. Claude KEEPS the template
  *      path (byte-identical parity with v1.1 + the .mcp.json parity test that
- *      compares against `claudeAdapter.emitMcpConfig`); other hosts use the
- *      adapter directly.
+ *      compares against `claudeAdapter.emitMcpConfig`) for a repo that has not
+ *      joined a workspace; a joined repo — one carrying a `.noir/workspace.json`
+ *      marker — gets the workspace entry instead, on every host, whatever
+ *      transport the run asked for (see the entry's own comment below).
  *
  * Skills are OUT OF SCOPE here — the cli composes `emitSkillsToDir` with
  * `adapter.skillsDir` + the host's `CompileTarget` (claude → `.claude/skills/`
@@ -546,10 +575,11 @@ 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}) carries three entries: the synthetic
- * `1.0.0 → 1.0.0` smoke test that exercises the runner end-to-end, and two real
- * version-to-version migrations, `1.0.0 → 1.1.0` and `1.1.0 → 1.2.0`. The
- * synthetic one is the copy-pasteable template for the next contributor.
+ * The registry ({@link MIGRATIONS}) carries four entries: the synthetic
+ * `1.0.0 → 1.0.0` smoke test that exercises the runner end-to-end, and three
+ * real version-to-version migrations, `1.0.0 → 1.1.0`, `1.1.0 → 1.2.0` and
+ * `1.2.0 → 1.3.0`. The synthetic one is the copy-pasteable template for the
+ * next contributor.
  */
 interface MigrationContext {
     /** Absolute repo root the migration operates on. */
@@ -558,6 +588,12 @@ interface MigrationContext {
      *  the same `changed`/`conflicts` shape, but does NOT touch disk. Used by
      *  `noir doctor`/CI to preview. */
     dryRun?: boolean;
+    /** The project's `rules.enabled` switch, when the caller knows it. False
+     *  tells a migration that `.noir/rules/RULES.md` is not part of this project
+     *  — the scaffold withholds the seed — so a migration must not write that
+     *  file back, however convincing its evidence for a refresh. Undefined means
+     *  enabled, which is the state of every project that predates the switch. */
+    rulesEnabled?: boolean;
 }
 interface MigrationResult {
     /** Repo-relative paths the migration modified (or would modify, in dryRun). */
@@ -598,6 +634,7 @@ interface MigrationScript {
  */
 declare function runMigrations(root: string, from: string | null, to: string, opts?: {
     dryRun?: boolean;
+    rulesEnabled?: boolean;
 }): MigrationResult & {
     from: string | null;
     to: string;
@@ -753,6 +790,18 @@ interface ScaffoldResult {
      *  mode is never changed. Optional so existing external constructors of this
      *  type (test stubs) stay valid; `scaffold()` always populates it. */
     fileModes?: Record<string, number>;
+    /** What the run did to the permissions of `.noir/.env` — the outcome of
+     *  {@link ensureOwnerOnly}, which is called on every run that may write, in
+     *  every mode, because the seeded file's 0600 mode is applied only when it is
+     *  created.
+     *  `'healed'` means a group/world-readable file was tightened to 0600, so a
+     *  caller can report the fix instead of leaving the user to notice it in a
+     *  later diagnostic; `'unchanged'` and `'unsupported'` mean nothing needed
+     *  doing (or the platform has no POSIX mode bits) — the `'unchanged'` a fresh
+     *  `create` reports, whose seed was written 0600 in the same run. Absent on a
+     *  dry run, which must not touch disk. Optional so existing external
+     *  constructors of this type stay valid. */
+    envMode?: EnvMode;
 }
 /** One entry in {@link ScaffoldResult.conflicts}. */
 interface ConflictRecord {
@@ -831,8 +880,11 @@ declare function scaffold(opts: ScaffoldOptions): Promise<ScaffoldResult>;
  * `key=value` shape is trivial to grep from a shell.
  */
 /** 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.2.0";
+ *  whenever a manifest entry, template, or migration changes shape. 1.3.0 adds
+ *  the migration that points a joined repo's MCP entry back at the workspace
+ *  bridge — a repair only the upgrade path can perform, so projects stamped
+ *  1.2.0 and below need a window that starts at their version to reach it. */
+declare const CURRENT_SCAFFOLD_VERSION = "1.3.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.
@@ -878,4 +930,4 @@ declare function loadTemplate(name: string): string;
 /** Resolve a template name to its absolute path (for diagnostics + tests). */
 declare function templatesDir(): string;
 
-export { BRIEF_BLOCK, type BuildHostArtifactsContext, type BuildManifestContext, CURRENT_SCAFFOLD_VERSION, type ConflictContext, type ConflictRecord, type ConflictResolution, type ConflictResolverReturn, type DiffLine, type HostTag, MANIFEST_PATH_PARITY, MIGRATIONS, type ManifestEntry, type MergeResult, type MigrationContext, type MigrationResult, type MigrationScript, SEED_TEMPLATE_HISTORY, type ScaffoldMode, type ScaffoldOptions, type ScaffoldResult, type SeedTemplateHistoryEntry, type StackInfo, type WriteMode, type WriteOutcome, ancestorsPath, applyInlineConflict, applyWithConflict, assertSafeRoot, buildHostArtifacts, buildManifest, buildRegion, detectStack, isStaleSeed, lineDiff, loadTemplate, managedBlock, mergeThreeWay, readAncestors, readScaffoldVersion, regenerate, render, runMigrations, scaffold, scaffoldVersionPath, skipIfExists, templatesDir, writeAncestors, writeScaffoldVersion, zdiff3Region };
+export { BRIEF_BLOCK, type BuildHostArtifactsContext, type BuildManifestContext, CURRENT_SCAFFOLD_VERSION, type ConflictContext, type ConflictRecord, type ConflictResolution, type ConflictResolverReturn, type DiffLine, type EnvMode, type HostTag, MANIFEST_PATH_PARITY, MIGRATIONS, type ManifestEntry, type MergeResult, type MigrationContext, type MigrationResult, type MigrationScript, SEED_TEMPLATE_HISTORY, type ScaffoldMode, type ScaffoldOptions, type ScaffoldResult, type SeedTemplateHistoryEntry, type StackInfo, type WriteMode, type WriteOutcome, ancestorsPath, applyInlineConflict, applyWithConflict, assertSafeRoot, buildHostArtifacts, buildManifest, buildRegion, detectStack, isStaleSeed, lineDiff, loadTemplate, managedBlock, mergeThreeWay, readAncestors, readScaffoldVersion, regenerate, render, runMigrations, scaffold, scaffoldVersionPath, skipIfExists, templatesDir, writeAncestors, writeScaffoldVersion, zdiff3Region };