create-next-pro-cli 0.1.27 → 0.1.29

package/dist/bin.node.js

@@ -1,131 +1,27 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import path8 from "path";
-
-// src/cli/onboarding.ts
-import path from "path";
-function configDirectory(context) {
-  return context.env.XDG_CONFIG_HOME ? path.join(context.env.XDG_CONFIG_HOME, "create-next-pro") : path.join(context.homeDir, ".config", "create-next-pro");
-}
-function configFile(context) {
-  return path.join(configDirectory(context), "config.json");
-}
-async function readConfig(context) {
-  try {
-    return JSON.parse(
-      await context.fs.readText(configFile(context))
-    );
-  } catch {
-    return null;
-  }
-}
-async function ensureLineInRc(context, target, line) {
-  try {
-    const current = context.fs.exists(target) ? await context.fs.readText(target) : "";
-    if (!current.includes(line))
-      await context.fs.appendText(target, `
-${line}
-`);
-  } catch {
-  }
-}
-async function installCompletion(context, shell) {
-  const directory = configDirectory(context);
-  const source = path.join(
-    context.packageRoot,
-    shell === "zsh" ? "create-next-pro-completion.zsh" : "create-next-pro-completion.sh"
-  );
-  const target = path.join(
-    directory,
-    `completion.${shell === "zsh" ? "zsh" : "sh"}`
-  );
-  await context.fs.mkdir(directory);
-  await context.fs.copyFile(source, target);
-  const rcFile = path.join(
-    context.homeDir,
-    shell === "zsh" ? ".zshrc" : ".bashrc"
-  );
-  await ensureLineInRc(context, rcFile, `source "${target}"`);
-}
-async function onboarding(context, version) {
-  context.terminal.log(`\u{1F680} Welcome to create-next-pro v${version}
-`);
-  const response = await context.prompt(
-    [
-      {
-        type: "select",
-        name: "shell",
-        message: "Which shell do you use?",
-        choices: [
-          { title: "zsh", value: "zsh" },
-          { title: "bash", value: "bash" }
-        ],
-        initial: context.env.SHELL?.includes("zsh") ? 0 : 1
-      },
-      {
-        type: "toggle",
-        name: "completion",
-        message: "Install autocompletion?",
-        initial: true,
-        active: "Yes",
-        inactive: "No"
-      }
-    ],
-    { onCancel: () => false }
-  );
-  if (response.shell !== "bash" && response.shell !== "zsh") {
-    throw new Error("Configuration cancelled.");
-  }
-  const now = (/* @__PURE__ */ new Date()).toISOString();
-  const config = {
-    version: 1,
-    shell: response.shell,
-    completionInstalled: Boolean(response.completion),
-    createdAt: now,
-    updatedAt: now
-  };
-  if (config.completionInstalled)
-    await installCompletion(context, config.shell);
-  await context.fs.mkdir(configDirectory(context));
-  await context.fs.writeText(
-    configFile(context),
-    JSON.stringify(config, null, 2)
-  );
-  context.terminal.log("\n\u2705 Configuration saved.");
-  context.terminal.log("you can now use the CLI ! ex : ");
-  context.terminal.log("  Without prompt (will change in future) :");
-  context.terminal.log("    create-next-pro my-next-project");
-  context.terminal.log("  With prompt :");
-  context.terminal.log("    create-next-pro");
-  context.terminal.log(
-    "For more information, visit: https://github.com/Rising-Corporation/create-next-pro-cli"
-  );
-  context.terminal.log("Happy coding!  \u{1F389}");
-  return config;
-}
+import path10 from "path";
 
 // src/cli/completion.ts
-import { readdir as readdir2 } from "fs/promises";
-import path3 from "path";
+import path2 from "path";
 
 // src/core/page-catalog.ts
-import { readdir } from "fs/promises";
-import path2 from "path";
+import path from "path";
 function isRouteGroup(segment) {
   return segment.startsWith("(") && segment.endsWith(")");
 }
-async function discoverPages(projectRoot) {
-  const appRoot = path2.join(projectRoot, "src", "app", "[locale]");
+async function discoverPages(projectRoot, fs) {
+  const appRoot = path.join(projectRoot, "src", "app", "[locale]");
   const candidates = [];
   async function visit(directory, relative = []) {
     let entries;
     try {
-      entries = await readdir(directory, { withFileTypes: true });
+      entries = await fs.list(directory);
     } catch {
       return;
     }
-    if (entries.some((entry) => entry.isFile() && entry.name === "page.tsx")) {
+    if (entries.some((entry) => entry.isFile && entry.name === "page.tsx")) {
       const routeSegments = relative.filter(
         (segment) => !isRouteGroup(segment)
       );
@@ -137,8 +33,8 @@ async function discoverPages(projectRoot) {
           logicalName,
           routeSegments,
           routeDirectory: directory,
-          uiDirectory: path2.join(projectRoot, "src", "ui", ...routeSegments),
-          messageFile: path2.join(
+          uiDirectory: path.join(projectRoot, "src", "ui", ...routeSegments),
+          messageFile: path.join(
             projectRoot,
             "messages",
             "{locale}",
@@ -149,8 +45,8 @@ async function discoverPages(projectRoot) {
       }
     }
     for (const entry of entries) {
-      if (entry.isDirectory() && !entry.name.startsWith(".")) {
-        await visit(path2.join(directory, entry.name), [
+      if (entry.isDirectory && !entry.name.startsWith(".")) {
+        await visit(path.join(directory, entry.name), [
           ...relative,
           entry.name
         ]);
@@ -174,6 +70,7 @@ var PUBLIC_COMMANDS = [
   "rmpage",
   "--help",
   "--version",
+  "--json",
   "--reconfigure"
 ];
 var OPTIONS = {
@@ -190,9 +87,9 @@ var OPTIONS = {
   ],
   addcomponent: ["--page", "-P"]
 };
-async function directories(root) {
+async function directories(root, context) {
   try {
-    return (await readdir2(root, { withFileTypes: true })).filter((entry) => entry.isDirectory() && !entry.name.startsWith("_")).map((entry) => entry.name).sort();
+    return (await context.fs.list(root)).filter((entry) => entry.isDirectory && !entry.name.startsWith("_")).map((entry) => entry.name).sort();
   } catch {
     return [];
   }
@@ -200,59 +97,466 @@ async function directories(root) {
 async function completionCandidates(command, context) {
   if (!command) return [...PUBLIC_COMMANDS];
   if (command === "rmpage") {
-    return (await discoverPages(context.cwd)).map(
+    return (await discoverPages(context.cwd, context.fs)).map(
       (candidate) => candidate.logicalName
     );
   }
   if (command === "addcomponent" || command === "addpage") {
     return [
       ...OPTIONS[command] ?? [],
-      ...await directories(path3.join(context.cwd, "src", "ui"))
+      ...await directories(path2.join(context.cwd, "src", "ui"), context)
     ];
   }
   if (command === "addlanguage")
     return ["de", "en", "es", "fr", "it", "ja", "pt"];
   return OPTIONS[command] ?? [];
 }
-async function printCompletions(args, context) {
-  for (const candidate of await completionCandidates(args[1], context)) {
-    context.terminal.log(candidate);
-  }
-}
+
+// src/cli/onboarding.ts
+import path4 from "path";
+
+// src/core/operations.ts
+import path3 from "path";
 
 // src/core/contracts.ts
-var success = () => ({ exitCode: 0 });
 var CliError = class extends Error {
-  constructor(message, exitCode = 1) {
+  exitCode;
+  code;
+  hint;
+  scope;
+  path;
+  constructor(message, options = {}) {
     super(message);
-    this.exitCode = exitCode;
     this.name = "CliError";
+    if (typeof options === "number") {
+      this.exitCode = options;
+      this.code = "FILESYSTEM_ERROR";
+    } else {
+      this.exitCode = options.exitCode ?? 1;
+      this.code = options.code ?? "FILESYSTEM_ERROR";
+      this.hint = options.hint;
+      this.scope = options.scope;
+      this.path = options.path;
+    }
+  }
+};
+
+// src/core/operations.ts
+var OperationJournal = class {
+  #events = [];
+  record(event) {
+    const detail = event.detail ? Object.fromEntries(
+      Object.entries(event.detail).map(([key, value]) => [
+        key,
+        /(content|credential|env|password|secret|token|value)/i.test(key) ? "[REDACTED]" : value
+      ])
+    ) : void 0;
+    const recorded = {
+      ...event,
+      detail,
+      sequence: this.#events.length + 1
+    };
+    this.#events.push(recorded);
+    return recorded;
+  }
+  snapshot() {
+    return this.#events.map((event) => ({ ...event }));
+  }
+  reset() {
+    this.#events.length = 0;
+  }
+};
+var MUTATIONS = /* @__PURE__ */ new Set(["created", "copied", "updated", "deleted"]);
+function statusFromEvents(events) {
+  if (events.some((event) => event.action === "cancelled")) return "cancelled";
+  return events.some((event) => MUTATIONS.has(event.action)) ? "success" : "unchanged";
+}
+function commandResult(context, input) {
+  const events = context.operations.snapshot();
+  const status = input.status ?? statusFromEvents(events);
+  return {
+    exitCode: status === "failed" ? 1 : 0,
+    status,
+    command: input.command,
+    summary: input.summary,
+    projectRoot: input.projectRoot,
+    configRoot: input.configRoot,
+    homeRoot: input.homeRoot,
+    events,
+    nextSteps: input.nextSteps ?? [],
+    error: null,
+    data: input.data
+  };
+}
+function failedResult(context, command, error, roots = {}) {
+  const cliError = error instanceof CliError ? error : void 0;
+  const normalized = {
+    code: cliError?.code ?? "FILESYSTEM_ERROR",
+    message: error instanceof Error ? error.message : String(error),
+    hint: cliError?.hint,
+    scope: cliError?.scope,
+    path: cliError?.path
+  };
+  const nextSteps = normalized.code === "ONBOARDING_REQUIRED" ? [
+    {
+      kind: "rerun",
+      required: true,
+      message: "Run create-next-pro once in human mode, then rerun the JSON command.",
+      paths: [{ scope: "config", path: "config.json" }],
+      commands: ["create-next-pro"]
+    }
+  ] : [];
+  context.operations.record({
+    action: "failed",
+    resource: "command",
+    role: command,
+    scope: normalized.scope ?? "project",
+    path: normalized.path ?? ".",
+    detail: { code: normalized.code }
+  });
+  return {
+    exitCode: cliError?.exitCode ?? 1,
+    status: "failed",
+    command,
+    summary: normalized.message,
+    ...roots,
+    events: context.operations.snapshot(),
+    nextSteps,
+    error: normalized
+  };
+}
+function relativeResource(root, target) {
+  const relative = path3.relative(path3.resolve(root), path3.resolve(target));
+  return relative || ".";
+}
+var MutationGateway = class {
+  constructor(context, root, defaultScope = "project") {
+    this.context = context;
+    this.root = root;
+    this.defaultScope = defaultScope;
+  }
+  context;
+  root;
+  defaultScope;
+  path(target) {
+    return relativeResource(this.root, target);
+  }
+  async mkdir(target, metadata, record = true) {
+    if (this.context.fs.exists(target)) {
+      if (record) this.record("unchanged", target, metadata);
+      return "unchanged";
+    }
+    await this.context.fs.mkdir(target);
+    if (record) this.record("created", target, metadata);
+    return "created";
+  }
+  async write(target, content, metadata) {
+    const exists = this.context.fs.exists(target);
+    if (exists && metadata.preserveExisting) {
+      this.record("unchanged", target, metadata);
+      return "unchanged";
+    }
+    if (exists && await this.context.fs.readText(target) === content) {
+      this.record("unchanged", target, metadata);
+      return "unchanged";
+    }
+    await this.context.fs.mkdir(path3.dirname(target));
+    await this.context.fs.writeText(target, content);
+    const action = exists ? "updated" : "created";
+    this.record(action, target, metadata);
+    return action;
+  }
+  async copy(source, target, metadata) {
+    if (this.context.fs.exists(target) && metadata.preserveExisting) {
+      this.record("unchanged", target, metadata);
+      return "unchanged";
+    }
+    await this.context.fs.mkdir(path3.dirname(target));
+    await this.context.fs.copyFile(source, target);
+    this.record("copied", target, {
+      ...metadata,
+      source: metadata.source ?? { path: source }
+    });
+    return "copied";
+  }
+  async remove(target, metadata, options = {}) {
+    if (!this.context.fs.exists(target)) {
+      this.record("unchanged", target, metadata);
+      return "unchanged";
+    }
+    await this.context.fs.remove(target, options);
+    this.record("deleted", target, metadata);
+    return "deleted";
+  }
+  unchanged(target, metadata) {
+    this.record("unchanged", target, metadata);
+  }
+  skipped(target, metadata) {
+    this.record("skipped", target, metadata);
+  }
+  record(action, target, metadata) {
+    this.context.operations.record({
+      action,
+      resource: metadata.resource ?? "file",
+      role: metadata.role,
+      scope: metadata.scope ?? this.defaultScope,
+      path: this.path(target),
+      source: metadata.source,
+      detail: metadata.detail
+    });
   }
-  exitCode;
 };
 
+// src/cli/onboarding.ts
+function configDirectory(context) {
+  return context.env.XDG_CONFIG_HOME ? path4.join(context.env.XDG_CONFIG_HOME, "create-next-pro") : path4.join(context.homeDir, ".config", "create-next-pro");
+}
+function configFile(context) {
+  return path4.join(configDirectory(context), "config.json");
+}
+async function readConfig(context) {
+  try {
+    const config = JSON.parse(
+      await context.fs.readText(configFile(context))
+    );
+    if (config.version !== 1 || config.shell !== "bash" && config.shell !== "zsh" || typeof config.completionInstalled !== "boolean" || typeof config.createdAt !== "string" || typeof config.updatedAt !== "string") {
+      return null;
+    }
+    return config;
+  } catch {
+    return null;
+  }
+}
+async function ensureLineInRc(context, target, line) {
+  const current = context.fs.exists(target) ? await context.fs.readText(target) : "";
+  const gateway = new MutationGateway(context, context.homeDir, "home");
+  return gateway.write(
+    target,
+    current.includes(line) ? current : `${current}
+${line}
+`,
+    { role: "shell-profile", resource: "shell-profile" }
+  );
+}
+async function installCompletion(context, shell) {
+  const directory = configDirectory(context);
+  const source = path4.join(
+    context.packageRoot,
+    shell === "zsh" ? "create-next-pro-completion.zsh" : "create-next-pro-completion.sh"
+  );
+  const target = path4.join(
+    directory,
+    `completion.${shell === "zsh" ? "zsh" : "sh"}`
+  );
+  const gateway = new MutationGateway(context, directory, "config");
+  await gateway.write(target, await context.fs.readText(source), {
+    role: "completion-script",
+    source: { scope: "package", path: path4.basename(source) }
+  });
+  const rcFile = path4.join(
+    context.homeDir,
+    shell === "zsh" ? ".zshrc" : ".bashrc"
+  );
+  await ensureLineInRc(context, rcFile, `source "${target}"`);
+}
+async function onboarding(context, version) {
+  const response = await context.prompt(
+    [
+      {
+        type: "select",
+        name: "shell",
+        message: "Which shell do you use?",
+        choices: [
+          { title: "zsh", value: "zsh" },
+          { title: "bash", value: "bash" }
+        ],
+        initial: context.env.SHELL?.includes("zsh") ? 0 : 1
+      },
+      {
+        type: "toggle",
+        name: "completion",
+        message: "Install autocompletion?",
+        initial: true,
+        active: "Yes",
+        inactive: "No"
+      }
+    ],
+    { onCancel: () => false }
+  );
+  if (response.shell !== "bash" && response.shell !== "zsh") {
+    context.operations.record({
+      action: "cancelled",
+      resource: "command",
+      role: "onboarding",
+      scope: "config",
+      path: "."
+    });
+    return commandResult(context, {
+      command: "onboarding",
+      summary: "Configuration was cancelled.",
+      configRoot: configDirectory(context),
+      homeRoot: context.homeDir,
+      status: "cancelled"
+    });
+  }
+  const previous = await readConfig(context);
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const config = {
+    version: 1,
+    shell: response.shell,
+    completionInstalled: Boolean(response.completion),
+    createdAt: previous?.createdAt ?? now,
+    updatedAt: now
+  };
+  if (config.completionInstalled) {
+    try {
+      await installCompletion(context, config.shell);
+    } catch (error) {
+      context.operations.record({
+        action: "skipped",
+        resource: "file",
+        role: "completion-installation",
+        scope: "config",
+        path: `completion.${config.shell === "zsh" ? "zsh" : "sh"}`,
+        detail: {
+          reason: error instanceof Error ? error.message : String(error)
+        }
+      });
+      config.completionInstalled = false;
+    }
+  }
+  const semanticallyUnchanged = previous?.shell === config.shell && previous.completionInstalled === config.completionInstalled;
+  if (semanticallyUnchanged && previous) config.updatedAt = previous.updatedAt;
+  const gateway = new MutationGateway(
+    context,
+    configDirectory(context),
+    "config"
+  );
+  await gateway.write(
+    configFile(context),
+    `${JSON.stringify(config, null, 2)}
+`,
+    { role: "user-configuration", resource: "configuration" }
+  );
+  return commandResult(context, {
+    command: "onboarding",
+    summary: `Configuration for create-next-pro v${version} is ready.`,
+    configRoot: configDirectory(context),
+    homeRoot: context.homeDir,
+    nextSteps: [
+      {
+        kind: "rerun",
+        required: true,
+        message: "Run the original create-next-pro command again.",
+        paths: []
+      }
+    ]
+  });
+}
+
+// src/cli/output.ts
+import path5 from "path";
+function rootFor(result, context, scope) {
+  if (scope === "project") return result.projectRoot;
+  if (scope === "config") return result.configRoot;
+  if (scope === "home") return result.homeRoot;
+  return context.packageRoot;
+}
+function displayPath(result, context, scope, target) {
+  const root = rootFor(result, context, scope);
+  return root ? path5.resolve(root, target) : target;
+}
+function renderEvent(result, context, event) {
+  const source = event.source?.template ? ` from template ${event.source.template}` : event.source?.path ? ` from ${displayPath(
+    result,
+    context,
+    event.source.scope ?? event.scope,
+    event.source.path
+  )}` : "";
+  const detail = event.detail ? ` (${Object.entries(event.detail).sort(([left], [right]) => left.localeCompare(right)).map(([key, value]) => `${key}=${JSON.stringify(value)}`).join(", ")})` : "";
+  return `${event.action.toUpperCase()} ${event.role}: ${displayPath(
+    result,
+    context,
+    event.scope,
+    event.path
+  )}${source}${detail}`;
+}
+function renderResult(result, context, mode) {
+  if (mode === "json") {
+    context.terminal.log(JSON.stringify({ schemaVersion: 1, ...result }));
+    return;
+  }
+  if (result.command === "help" && typeof result.data?.help === "string") {
+    context.terminal.log(result.data.help);
+    return;
+  }
+  if (result.command === "version" && typeof result.data?.version === "string") {
+    context.terminal.log(`v${result.data.version}`);
+    return;
+  }
+  const copiedTemplateFiles = result.events.filter(
+    (event) => event.action === "copied" && event.role === "template-file"
+  );
+  if (copiedTemplateFiles.length > 0) {
+    context.terminal.log(
+      `COPIED ${copiedTemplateFiles.length} template files to ${result.projectRoot}.`
+    );
+  }
+  for (const event of result.events) {
+    if (event.action === "copied" && event.role === "template-file") continue;
+    const line = renderEvent(result, context, event);
+    if (event.action === "failed") context.terminal.error(line);
+    else if (event.action === "skipped") context.terminal.warn(line);
+    else context.terminal.log(line);
+  }
+  if (result.error) {
+    context.terminal.error(
+      `ERROR [${result.error.code}]: ${result.error.message}`
+    );
+    if (result.error.hint) context.terminal.error(`HINT: ${result.error.hint}`);
+  } else if (result.status === "success") {
+    context.terminal.log(`SUCCESS: ${result.summary}`);
+  } else if (result.status === "unchanged") {
+    context.terminal.log(`NO CHANGES: ${result.summary}`);
+  } else if (result.status === "cancelled") {
+    context.terminal.log(`CANCELLED: ${result.summary}`);
+  }
+  for (const step of result.nextSteps) {
+    context.terminal.log(`NEXT [${step.kind}]: ${step.message}`);
+    for (const target of step.paths) {
+      context.terminal.log(
+        `  ${displayPath(result, context, target.scope, target.path)}`
+      );
+    }
+    for (const command of step.commands ?? []) {
+      context.terminal.log(`  ${command}`);
+    }
+  }
+}
+
 // src/lib/addApi.ts
 import { join as join2 } from "path";
-import { mkdir as mkdir2, readFile as readFile3, writeFile as writeFile2 } from "fs/promises";
-import prompts2 from "prompts";
-import { existsSync as existsSync3 } from "fs";
 
 // src/lib/utils.ts
-import { readFile } from "fs/promises";
-import { existsSync } from "fs";
 import { join } from "path";
 function capitalize(str) {
   return str.charAt(0).toUpperCase() + str.slice(1);
 }
+function toIdentifier(value) {
+  return value.replace(
+    /[-_]+([A-Za-z0-9])/g,
+    (_, character) => character.toUpperCase()
+  );
+}
 function configuredAliasPrefix(config) {
   const alias = config.importAlias ?? "@/*";
   return alias.endsWith("/*") ? alias.slice(0, -2) : "@";
 }
-async function loadConfig(cwd = process.cwd()) {
-  const configPath = join(cwd, "cnp.config.json");
-  if (!existsSync(configPath)) return null;
+async function loadConfig(context) {
+  const configPath = join(context.cwd, "cnp.config.json");
+  if (!context.fs.exists(configPath)) return null;
   try {
-    const raw = await readFile(configPath, "utf-8");
+    const raw = await context.fs.readText(configPath);
     return JSON.parse(raw);
   } catch {
     return null;
@@ -283,66 +587,8 @@ function toFileName(key) {
   }
 }
 
-// src/runtime/node-context.ts
-import { existsSync as existsSync2 } from "fs";
-import {
-  appendFile,
-  copyFile,
-  mkdir,
-  readFile as readFile2,
-  writeFile
-} from "fs/promises";
-import os from "os";
-import path4 from "path";
-import { fileURLToPath } from "url";
-import prompts from "prompts";
-function findPackageRoot(start) {
-  let current = start;
-  while (true) {
-    const packagePath = path4.join(current, "package.json");
-    if (existsSync2(packagePath)) return current;
-    const parent = path4.dirname(current);
-    if (parent === current) {
-      throw new Error(`Unable to locate package.json from ${start}`);
-    }
-    current = parent;
-  }
-}
-function resolvePackageRoot(metaUrl = import.meta.url) {
-  return findPackageRoot(path4.dirname(fileURLToPath(metaUrl)));
-}
-function createNodeContext(overrides = {}) {
-  return {
-    argv: process.argv.slice(2),
-    cwd: process.cwd(),
-    env: process.env,
-    homeDir: os.homedir(),
-    packageRoot: resolvePackageRoot(),
-    terminal: console,
-    prompt: prompts,
-    fs: {
-      exists: existsSync2,
-      readText: (target) => readFile2(target, "utf8"),
-      writeText: async (target, content) => {
-        await writeFile(target, content);
-      },
-      mkdir: async (target) => {
-        await mkdir(target, { recursive: true });
-      },
-      copyFile: async (source, target) => {
-        await copyFile(source, target);
-      },
-      appendText: async (target, content) => {
-        await appendFile(target, content);
-      }
-    },
-    ...overrides
-  };
-}
-
 // src/core/project-paths.ts
-import path5 from "path";
-import { lstat } from "fs/promises";
+import path6 from "path";
 var SAFE_SEGMENT = /^[A-Za-z][A-Za-z0-9_-]*$/;
 function hasControlCharacters(value) {
   return [...value].some((character) => {
@@ -353,56 +599,58 @@ function hasControlCharacters(value) {
 function parseLogicalName(value, label = "name") {
   if (!value || hasControlCharacters(value)) {
     throw new CliError(
-      `Invalid ${label}: a non-empty printable value is required.`
+      `Invalid ${label}: a non-empty printable value is required.`,
+      { code: "INVALID_ARGUMENT" }
     );
   }
-  if (path5.isAbsolute(value) || value.includes("/") || value.includes("\\")) {
+  if (path6.isAbsolute(value) || value.includes("/") || value.includes("\\")) {
     throw new CliError(
-      `Invalid ${label}: paths and separators are not allowed.`
+      `Invalid ${label}: paths and separators are not allowed.`,
+      { code: "INVALID_ARGUMENT" }
     );
   }
   const segments = value.split(".");
   if (segments.some((segment) => !SAFE_SEGMENT.test(segment))) {
     throw new CliError(
-      `Invalid ${label}: use dot-separated alphanumeric segments beginning with a letter.`
+      `Invalid ${label}: use dot-separated alphanumeric segments beginning with a letter.`,
+      { code: "INVALID_ARGUMENT" }
     );
   }
   return segments;
 }
 function validateProjectName(value) {
-  if (!value || hasControlCharacters(value) || path5.isAbsolute(value) || value === "." || value === ".." || value.includes("/") || value.includes("\\") || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(value)) {
+  if (!value || hasControlCharacters(value) || path6.isAbsolute(value) || value === "." || value === ".." || value.includes("/") || value.includes("\\") || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(value)) {
     throw new CliError(
-      "Invalid project name: use letters, numbers, dots, dashes or underscores without path separators."
+      "Invalid project name: use letters, numbers, dots, dashes or underscores without path separators.",
+      { code: "INVALID_ARGUMENT" }
     );
   }
   return value;
 }
 function resolveInside(root, ...segments) {
-  const absoluteRoot = path5.resolve(root);
-  const target = path5.resolve(absoluteRoot, ...segments);
-  if (target !== absoluteRoot && !target.startsWith(`${absoluteRoot}${path5.sep}`)) {
+  const absoluteRoot = path6.resolve(root);
+  const target = path6.resolve(absoluteRoot, ...segments);
+  if (target !== absoluteRoot && !target.startsWith(`${absoluteRoot}${path6.sep}`)) {
     throw new CliError(
-      `Refusing to access a path outside the project: ${target}`
+      `Refusing to access a path outside the project: ${target}`,
+      { code: "UNSAFE_PATH" }
     );
   }
   return target;
 }
-async function assertSafeTarget(root, target) {
-  const safeTarget = resolveInside(root, path5.relative(root, target));
-  const relativeSegments = path5.relative(path5.resolve(root), safeTarget).split(path5.sep);
-  let current = path5.resolve(root);
+async function assertSafeTarget(root, target, fs) {
+  const safeTarget = resolveInside(root, path6.relative(root, target));
+  const relativeSegments = path6.relative(path6.resolve(root), safeTarget).split(path6.sep);
+  let current = path6.resolve(root);
   for (const segment of relativeSegments) {
     if (!segment) continue;
-    current = path5.join(current, segment);
-    try {
-      if ((await lstat(current)).isSymbolicLink()) {
-        throw new CliError(
-          `Symbolic links are forbidden in project paths: ${current}`
-        );
-      }
-    } catch (error) {
-      if (error instanceof CliError) throw error;
-      if (error.code !== "ENOENT") throw error;
+    current = path6.join(current, segment);
+    const entry = await fs.inspect(current);
+    if (entry?.isSymbolicLink) {
+      throw new CliError(
+        `Symbolic links are forbidden in project paths: ${current}`,
+        { code: "UNSAFE_PATH" }
+      );
     }
   }
   return safeTarget;
@@ -410,764 +658,1233 @@ async function assertSafeTarget(root, target) {
 function normalizeImportAlias(value) {
   if (!/^[A-Za-z@~][A-Za-z0-9@~_-]*\/\*$/.test(value)) {
     throw new CliError(
-      'Invalid import alias: expected a prefix followed by "/*" (for example "@/*" or "@core/*").'
+      'Invalid import alias: expected a prefix followed by "/*" (for example "@/*" or "@core/*").',
+      { code: "INVALID_ARGUMENT" }
     );
   }
   return value;
 }
 
 // src/lib/addApi.ts
-async function addApi(args, cwd = process.cwd()) {
+var addApi = async (args, context) => {
   let apiName = args[1];
   if (!apiName || apiName.startsWith("-")) {
-    const response = await prompts2.prompt({
+    if (context.outputMode === "json") {
+      throw new CliError("API route name is required in JSON mode.", {
+        code: "INTERACTIVE_INPUT_REQUIRED",
+        hint: "Pass the API route name after addapi."
+      });
+    }
+    const response = await context.prompt({
       type: "text",
       name: "apiName",
-      message: "\u{1F50C} API route name to add:",
+      message: "API route name to add:",
       validate: (name) => name ? true : "API route name is required"
     });
-    apiName = response.apiName;
+    apiName = String(response.apiName ?? "");
+    if (!apiName) {
+      context.operations.record({
+        action: "cancelled",
+        resource: "command",
+        role: "api-creation",
+        scope: "project",
+        path: "."
+      });
+      return commandResult(context, {
+        command: "addapi",
+        summary: "API route creation was cancelled.",
+        projectRoot: context.cwd,
+        status: "cancelled"
+      });
+    }
   }
   const apiSegments = parseLogicalName(apiName, "API route name");
-  const config = await loadConfig(cwd);
+  const config = await loadConfig(context);
   if (!config) {
-    console.error(
-      "\u274C Configuration file cnp.config.json not found. Run this command from the project root."
-    );
-    return;
-  }
-  const apiDir = join2(cwd, "src", "app", "api", ...apiSegments);
-  await assertSafeTarget(cwd, apiDir);
-  if (!existsSync3(apiDir)) {
-    await mkdir2(apiDir, { recursive: true });
+    throw new CliError("Configuration file cnp.config.json was not found.", {
+      code: "CONFIG_NOT_FOUND",
+      hint: "Run this command from the generated project root."
+    });
   }
-  const templateDir = join2(
-    resolvePackageRoot(import.meta.url),
-    "templates",
-    "Api"
-  );
+  const apiDir = join2(context.cwd, "src", "app", "api", ...apiSegments);
+  await assertSafeTarget(context.cwd, apiDir, context.fs);
+  const gateway = new MutationGateway(context, context.cwd);
+  const templateDir = join2(context.packageRoot, "templates", "Api");
   const routeTemplate = join2(templateDir, "route.ts");
   const routePath = join2(apiDir, "route.ts");
-  if (!existsSync3(routePath)) {
-    if (existsSync3(routeTemplate)) {
-      let content = await readFile3(routeTemplate, "utf-8");
-      content = content.replace(/template/g, apiName);
-      await writeFile2(routePath, content);
-    } else {
-      await writeFile2(
-        routePath,
-        `import { NextResponse } from "next/server";
-
-export async function GET() {
-  return NextResponse.json({ message: "Hello from ${apiName}" });
-}
-`
-      );
-    }
-    console.log(`\u{1F4C4} File created: ${routePath}`);
-  } else {
-    console.log(`\u2139\uFE0F File already exists: ${routePath}`);
+  if (!context.fs.exists(routeTemplate)) {
+    throw new CliError("API template route.ts was not found.", {
+      code: "TEMPLATE_MISSING",
+      scope: "package",
+      path: "templates/Api/route.ts"
+    });
   }
-  console.log(`\u2705 API route "${apiName}" added.`);
-}
+  await gateway.mkdir(apiDir, {
+    role: "api-directory",
+    resource: "directory"
+  });
+  const content = (await context.fs.readText(routeTemplate)).replace(
+    /template/g,
+    apiName
+  );
+  const action = await gateway.write(routePath, content, {
+    role: "api-route",
+    preserveExisting: true
+  });
+  return commandResult(context, {
+    command: "addapi",
+    summary: action === "unchanged" ? `API route "${apiName}" already exists and was preserved.` : `Added API route "${apiName}".`,
+    projectRoot: context.cwd,
+    nextSteps: action === "unchanged" ? [] : [
+      {
+        kind: "review",
+        required: true,
+        message: "Replace the example response and review validation and authentication.",
+        paths: [{ scope: "project", path: gateway.path(routePath) }]
+      },
+      {
+        kind: "run-checks",
+        required: true,
+        message: "Run the project checks.",
+        paths: [],
+        commands: ["bun run check", "npm run check", "pnpm run check"]
+      }
+    ]
+  });
+};
 
 // src/lib/addComponent.ts
 import { join as join3 } from "path";
-import { mkdir as mkdir3, readFile as readFile4, writeFile as writeFile3, readdir as readdir3 } from "fs/promises";
-import prompts3 from "prompts";
-import { existsSync as existsSync4, statSync } from "fs";
-async function addComponent(args, cwd = process.cwd()) {
+var addComponent = async (args, context) => {
   let componentName = args[1];
-  let pageScope = null;
-  const pageIndex = args.findIndex((arg) => arg === "-P" || arg === "--page");
-  if (pageIndex !== -1 && args[pageIndex + 1]) {
-    pageScope = args[pageIndex + 1];
-  }
-  let nestedPath = null;
-  if (pageScope && pageScope.includes(".")) {
-    nestedPath = join3(...pageScope.split("."));
+  const pageIndex = args.findIndex(
+    (argument) => argument === "-P" || argument === "--page"
+  );
+  const pageScope = pageIndex >= 0 ? args[pageIndex + 1] : void 0;
+  if (pageIndex >= 0 && !pageScope) {
+    throw new CliError("The --page option requires a page name.", {
+      code: "INVALID_ARGUMENT"
+    });
   }
   if (!componentName || componentName.startsWith("-")) {
-    const response = await prompts3.prompt({
+    if (context.outputMode === "json") {
+      throw new CliError("Component name is required in JSON mode.", {
+        code: "INTERACTIVE_INPUT_REQUIRED",
+        hint: "Pass the component name after addcomponent."
+      });
+    }
+    const response = await context.prompt({
       type: "text",
       name: "componentName",
-      message: "\u{1F9E9} Component name to add:",
+      message: "Component name to add:",
       validate: (name) => name ? true : "Component name is required"
     });
-    componentName = response.componentName;
+    componentName = String(response.componentName ?? "");
+    if (!componentName) {
+      context.operations.record({
+        action: "cancelled",
+        resource: "command",
+        role: "component-creation",
+        scope: "project",
+        path: "."
+      });
+      return commandResult(context, {
+        command: "addcomponent",
+        summary: "Component creation was cancelled.",
+        projectRoot: context.cwd,
+        status: "cancelled"
+      });
+    }
+  }
+  const componentSegments = parseLogicalName(componentName, "component name");
+  if (componentSegments.length !== 1) {
+    throw new CliError("Component names must contain exactly one segment.", {
+      code: "INVALID_ARGUMENT"
+    });
   }
-  parseLogicalName(componentName, "component name");
-  if (pageScope) parseLogicalName(pageScope, "page name");
-  const config = await loadConfig(cwd);
+  const pageSegments = pageScope ? parseLogicalName(pageScope, "page name") : [];
+  const config = await loadConfig(context);
   if (!config) {
-    console.error(
-      "\u274C Configuration file cnp.config.json not found. Run this command from the project root."
-    );
-    return;
+    throw new CliError("Configuration file cnp.config.json was not found.", {
+      code: "CONFIG_NOT_FOUND",
+      hint: "Run this command from the generated project root."
+    });
   }
-  const useI18n = !!config.useI18n;
-  const componentNameUpper = capitalize(componentName);
-  const templatePath = join3(
-    resolvePackageRoot(import.meta.url),
-    "templates",
-    "Component"
-  );
-  let messagesPath = null;
-  if (useI18n) {
-    messagesPath = join3(cwd, "messages");
-    if (!existsSync4(messagesPath)) {
-      console.error(
-        "\u274C Messages directory missing. Ensure i18n was configured."
-      );
-      return;
-    }
+  const componentNameUpper = capitalize(toIdentifier(componentName));
+  const templateRoot = join3(context.packageRoot, "templates", "Component");
+  const componentTemplate = join3(templateRoot, "Component.tsx");
+  const messagesTemplate = join3(templateRoot, "component.json");
+  if (!context.fs.exists(componentTemplate) || config.useI18n && !context.fs.exists(messagesTemplate)) {
+    throw new CliError("Required component template files were not found.", {
+      code: "TEMPLATE_MISSING",
+      scope: "package",
+      path: "templates/Component"
+    });
   }
-  let componentTargetPath;
-  let translationKey;
-  if (pageScope) {
-    if (nestedPath) {
-      componentTargetPath = join3(cwd, "src", "ui", nestedPath);
-      translationKey = pageScope;
-    } else {
-      componentTargetPath = join3(cwd, "src", "ui", pageScope);
-      translationKey = pageScope;
+  const targetDirectory = pageScope ? join3(context.cwd, "src", "ui", ...pageSegments) : join3(context.cwd, "src", "ui", "_global");
+  await assertSafeTarget(context.cwd, targetDirectory, context.fs);
+  const componentFile = join3(targetDirectory, `${componentNameUpper}.tsx`);
+  const translationNamespace = pageScope ?? "_global_ui";
+  const componentContent = (await context.fs.readText(componentTemplate)).replace(/Component/g, componentNameUpper).replace(/componentPage/g, translationNamespace);
+  const preparedMessages = [];
+  if (config.useI18n) {
+    const messagesRoot = join3(context.cwd, "messages");
+    if (!context.fs.exists(messagesRoot)) {
+      throw new CliError("The messages directory was not found.", {
+        code: "CONFIG_NOT_FOUND",
+        scope: "project",
+        path: "messages"
+      });
     }
-  } else {
-    componentTargetPath = join3(cwd, "src", "ui", "_global");
-    translationKey = "_global_ui";
-  }
-  await assertSafeTarget(cwd, componentTargetPath);
-  if (!existsSync4(componentTargetPath)) {
-    await mkdir3(componentTargetPath, { recursive: true });
-  }
-  const componentFile = join3(componentTargetPath, `${componentNameUpper}.tsx`);
-  const templateComponentPath = join3(templatePath, "Component.tsx");
-  if (existsSync4(templateComponentPath)) {
-    let content = await readFile4(templateComponentPath, "utf-8");
-    content = content.replace(/Component/g, componentNameUpper).replace(/componentPage/g, translationKey);
-    await writeFile3(componentFile, content);
-    console.log(`\u{1F4C4} File created: ${componentFile}`);
-  } else {
-    console.error(
-      "\u274C Template Component.tsx introuvable :",
-      templateComponentPath
+    const templateMessages = JSON.parse(
+      await context.fs.readText(messagesTemplate)
     );
-  }
-  if (useI18n && messagesPath) {
-    const entries = await readdir3(messagesPath, { withFileTypes: true });
-    const langDirs = entries.filter((e) => e.isDirectory()).map((e) => e.name);
-    const jsonTemplate = join3(templatePath, "component.json");
-    if (!existsSync4(jsonTemplate)) {
-      console.error("\u274C Template component.json not found:", jsonTemplate);
-      return;
+    const locales = (await context.fs.list(messagesRoot)).filter((entry) => entry.isDirectory).map((entry) => entry.name).sort();
+    if (locales.length === 0) {
+      throw new CliError("No locale directories were found.", {
+        code: "CONFIG_NOT_FOUND",
+        scope: "project",
+        path: "messages"
+      });
     }
-    const jsonContent = await readFile4(jsonTemplate, "utf-8");
-    const parsed = JSON.parse(jsonContent);
-    for (const locale of langDirs) {
-      const localeDir = join3(messagesPath, locale);
-      if (!existsSync4(localeDir) || !statSync(localeDir).isDirectory())
-        continue;
-      let jsonTarget;
-      if (pageScope) {
-        const [messageFile] = pageScope.split(".");
-        jsonTarget = join3(messagesPath, locale, `${messageFile}.json`);
-      } else {
-        jsonTarget = join3(messagesPath, locale, `_global_ui.json`);
-      }
-      let current = {};
-      if (existsSync4(jsonTarget)) {
-        const jsonFile = await readFile4(jsonTarget, "utf-8");
-        current = JSON.parse(jsonFile);
+    for (const locale of locales) {
+      const messageFile = pageScope ? pageSegments[0] : "_global_ui";
+      const target = join3(messagesRoot, locale, `${messageFile}.json`);
+      let data = {};
+      if (context.fs.exists(target)) {
+        try {
+          data = JSON.parse(await context.fs.readText(target));
+        } catch {
+          throw new CliError(
+            `Invalid JSON in messages/${locale}/${messageFile}.json.`,
+            {
+              code: "FILESYSTEM_ERROR",
+              scope: "project",
+              path: `messages/${locale}/${messageFile}.json`
+            }
+          );
+        }
       }
-      if (pageScope?.includes(".")) {
-        const child = pageScope.split(".")[1];
-        const childMessages = current[child] && typeof current[child] === "object" ? current[child] : {};
-        childMessages[componentNameUpper] = parsed;
-        current[child] = childMessages;
-      } else {
-        current[componentNameUpper] = parsed;
+      let container = data;
+      if (pageSegments.length > 1) {
+        const child = pageSegments[1];
+        const current = data[child];
+        if (current !== void 0 && (!current || typeof current !== "object" || Array.isArray(current))) {
+          throw new CliError(
+            `Translation namespace ${pageScope} is not an object in ${locale}.`,
+            {
+              code: "INVALID_ARGUMENT",
+              scope: "project",
+              path: `messages/${locale}/${messageFile}.json`
+            }
+          );
+        }
+        if (!current) data[child] = {};
+        container = data[child];
       }
-      await writeFile3(jsonTarget, JSON.stringify(current, null, 2));
-      console.log(`\u{1F4C4} File updated: ${jsonTarget}`);
+      const exists = Object.hasOwn(container, componentNameUpper);
+      if (!exists) container[componentNameUpper] = templateMessages;
+      preparedMessages.push({
+        locale,
+        target,
+        exists,
+        content: exists ? void 0 : `${JSON.stringify(data, null, 2)}
+`
+      });
     }
-  } else {
-    console.log("\u2139\uFE0F Skipping translation entries; next-intl not enabled.");
   }
-  console.log(
-    `\u2705 Component "${componentNameUpper}" added ${pageScope ? `to page ${pageScope}` : "globally"}${useI18n ? " with localized messages" : ""}.`
-  );
-}
+  const gateway = new MutationGateway(context, context.cwd);
+  await gateway.mkdir(targetDirectory, {
+    role: "component-directory",
+    resource: "directory"
+  });
+  await gateway.write(componentFile, componentContent, {
+    role: "ui-component",
+    preserveExisting: true
+  });
+  for (const item of preparedMessages) {
+    if (item.exists) {
+      gateway.unchanged(item.target, {
+        role: "translation-messages",
+        detail: {
+          locale: item.locale,
+          key: `${translationNamespace}.${componentNameUpper}`
+        }
+      });
+    } else {
+      await gateway.write(item.target, item.content, {
+        role: "translation-messages",
+        detail: {
+          locale: item.locale,
+          key: `${translationNamespace}.${componentNameUpper}`
+        }
+      });
+    }
+  }
+  const mutated = context.operations.snapshot().some((event) => event.action === "created" || event.action === "updated");
+  return commandResult(context, {
+    command: "addcomponent",
+    summary: mutated ? `Added component "${componentNameUpper}" ${pageScope ? `to page "${pageScope}"` : "globally"}.` : `Component "${componentNameUpper}" already exists and was preserved.`,
+    projectRoot: context.cwd,
+    nextSteps: mutated ? [
+      {
+        kind: "review",
+        required: true,
+        message: "Review the generated component and its localized messages.",
+        paths: [
+          { scope: "project", path: gateway.path(componentFile) },
+          ...preparedMessages.map((item) => ({
+            scope: "project",
+            path: gateway.path(item.target)
+          }))
+        ]
+      },
+      {
+        kind: "run-checks",
+        required: true,
+        message: "Run the project checks.",
+        paths: [],
+        commands: ["bun run check", "npm run check", "pnpm run check"]
+      }
+    ] : []
+  });
+};
 
 // src/lib/addLanguage.ts
 import { join as join4 } from "path";
-import { existsSync as existsSync5 } from "fs";
-import { cp, readFile as readFile5, writeFile as writeFile4 } from "fs/promises";
-import prompts4 from "prompts";
 function generateLocales() {
-  const dn = new Intl.DisplayNames(["en"], { type: "language" });
+  const names = new Intl.DisplayNames(["en"], { type: "language" });
   const locales = [];
-  for (let i = 0; i < 26; i++) {
-    for (let j = 0; j < 26; j++) {
-      const code = String.fromCharCode(97 + i) + String.fromCharCode(97 + j);
+  for (let first = 0; first < 26; first++) {
+    for (let second = 0; second < 26; second++) {
+      const code = String.fromCharCode(97 + first, 97 + second);
       try {
-        const name = dn.of(code);
-        if (name && name.toLowerCase() !== code) {
-          locales.push(code);
-        }
+        const name = names.of(code);
+        if (name && name.toLowerCase() !== code) locales.push(code);
       } catch {
       }
     }
   }
   return locales.sort();
 }
-async function addLanguage(args, cwd = process.cwd()) {
-  const config = await loadConfig(cwd);
+async function listFiles(context, root) {
+  const files = [];
+  async function visit(directory, relative = "") {
+    for (const entry of await context.fs.list(directory)) {
+      const next = relative ? `${relative}/${entry.name}` : entry.name;
+      if (entry.isSymbolicLink) {
+        throw new CliError(`Symbolic link found in locale source: ${next}`, {
+          code: "UNSAFE_PATH",
+          scope: "project",
+          path: next
+        });
+      }
+      if (entry.isDirectory) await visit(join4(directory, entry.name), next);
+      else if (entry.isFile) files.push(next);
+    }
+  }
+  await visit(root);
+  return files.sort();
+}
+var addLanguage = async (args, context) => {
+  const config = await loadConfig(context);
   if (!config?.useI18n) {
-    console.error("\u274C i18n is not enabled in this project.");
-    return;
+    throw new CliError("Internationalization is not enabled in this project.", {
+      code: "I18N_DISABLED"
+    });
   }
-  const messagesPath = join4(cwd, "messages");
-  if (!existsSync5(messagesPath)) {
-    console.error("\u274C Messages directory missing. Ensure i18n was configured.");
-    return;
+  const messagesRoot = join4(context.cwd, "messages");
+  if (!context.fs.exists(messagesRoot)) {
+    throw new CliError("The messages directory was not found.", {
+      code: "CONFIG_NOT_FOUND",
+      scope: "project",
+      path: "messages"
+    });
   }
   const available = generateLocales();
   let locale = args[1];
-  if (!locale || !available.includes(locale)) {
-    const response = await prompts4({
+  if (!locale) {
+    if (context.outputMode === "json") {
+      throw new CliError("Locale is required in JSON mode.", {
+        code: "INTERACTIVE_INPUT_REQUIRED",
+        hint: "Pass a two-letter locale after addlanguage."
+      });
+    }
+    const response = await context.prompt({
       type: "autocomplete",
       name: "locale",
-      message: "\u{1F310} Locale to add:",
-      choices: available.map((l) => ({ title: l, value: l }))
+      message: "Locale to add:",
+      choices: available.map((value) => ({ title: value, value }))
     });
-    locale = response.locale;
+    locale = String(response.locale ?? "");
+    if (!locale) {
+      context.operations.record({
+        action: "cancelled",
+        resource: "command",
+        role: "locale-creation",
+        scope: "project",
+        path: "."
+      });
+      return commandResult(context, {
+        command: "addlanguage",
+        summary: "Locale creation was cancelled.",
+        projectRoot: context.cwd,
+        status: "cancelled"
+      });
+    }
   }
-  if (!locale) return;
   parseLogicalName(locale, "locale");
-  await assertSafeTarget(cwd, messagesPath);
-  if (existsSync5(join4(messagesPath, locale))) {
-    throw new Error(`Locale ${locale} already exists.`);
+  if (!available.includes(locale)) {
+    throw new CliError(`Unsupported locale code: ${locale}.`, {
+      code: "INVALID_ARGUMENT",
+      hint: "Use a recognized two-letter language code."
+    });
   }
-  const routingFile = join4(cwd, "src", "lib", "i18n", "routing.ts");
-  const messagesRegistryFile = join4(cwd, "src", "lib", "i18n", "messages.ts");
-  if (!existsSync5(routingFile)) {
-    throw new Error("routing.ts not found. Are you in project root?");
+  const routingFile = join4(context.cwd, "src", "lib", "i18n", "routing.ts");
+  const registryFile = join4(context.cwd, "src", "lib", "i18n", "messages.ts");
+  if (!context.fs.exists(routingFile) || !context.fs.exists(registryFile)) {
+    throw new CliError(
+      "Required i18n routing or registry file was not found.",
+      {
+        code: "CONFIG_NOT_FOUND",
+        scope: "project",
+        path: "src/lib/i18n"
+      }
+    );
   }
-  if (!existsSync5(messagesRegistryFile)) {
-    throw new Error("messages.ts not found. Are you in project root?");
+  const routing = await context.fs.readText(routingFile);
+  const defaultLocale = routing.match(/defaultLocale:\s*["']([^"']+)["']/)?.[1];
+  if (!defaultLocale) {
+    throw new CliError(
+      "The default locale could not be resolved from routing.ts.",
+      {
+        code: "CONFIG_NOT_FOUND",
+        scope: "project",
+        path: "src/lib/i18n/routing.ts"
+      }
+    );
   }
-  const routingContent = await readFile5(routingFile, "utf-8");
-  const defaultMatch = routingContent.match(/defaultLocale:\s*"([^"]+)"/);
-  const defaultLocale = defaultMatch ? defaultMatch[1] : null;
-  if (!defaultLocale || !existsSync5(join4(messagesPath, defaultLocale))) {
-    throw new Error("Default locale not found.");
+  const sourceDirectory = join4(messagesRoot, defaultLocale);
+  const sourceAggregator = join4(messagesRoot, `${defaultLocale}.ts`);
+  if (!context.fs.exists(sourceDirectory)) {
+    throw new CliError(
+      `Default locale directory ${defaultLocale} was not found.`,
+      {
+        code: "CONFIG_NOT_FOUND",
+        scope: "project",
+        path: `messages/${defaultLocale}`
+      }
+    );
   }
-  const defaultAggregatorFile = join4(messagesPath, `${defaultLocale}.ts`);
-  if (!existsSync5(defaultAggregatorFile)) {
-    throw new Error(`Default locale aggregator not found: ${defaultLocale}.ts`);
+  if (!context.fs.exists(sourceAggregator)) {
+    throw new CliError("Default locale aggregator not found.", {
+      code: "CONFIG_NOT_FOUND",
+      scope: "project",
+      path: `messages/${defaultLocale}.ts`
+    });
   }
-  const localesMatch = routingContent.match(/locales:\s*\[([^\]]*)\]/);
-  if (!localesMatch) {
-    throw new Error("Unable to locate routing locales.");
+  const sourceFiles = await listFiles(context, sourceDirectory);
+  if (sourceFiles.length === 0) {
+    throw new CliError(`Default locale ${defaultLocale} contains no files.`, {
+      code: "CONFIG_NOT_FOUND",
+      scope: "project",
+      path: `messages/${defaultLocale}`
+    });
   }
-  const localesArr = localesMatch[1].split(",").map((s) => s.trim().replace(/["']/g, "")).filter(Boolean);
-  if (localesArr.includes(locale)) {
-    throw new Error(`Locale ${locale} already exists in routing.`);
+  const defaultAggregator = await context.fs.readText(sourceAggregator);
+  const importPrefix = `./${defaultLocale}/`;
+  if (!defaultAggregator.includes(importPrefix)) {
+    throw new CliError(
+      `Default aggregator does not import from ${importPrefix}.`,
+      {
+        code: "CONFIG_NOT_FOUND",
+        scope: "project",
+        path: `messages/${defaultLocale}.ts`
+      }
+    );
   }
-  const newLocales = `locales: [${[...localesArr, locale].map((item) => `"${item}"`).join(", ")}]`;
-  const nextRoutingContent = routingContent.replace(
-    /locales:\s*\[[^\]]*\]/,
-    newLocales
-  );
-  const defaultAggregatorContent = await readFile5(
-    defaultAggregatorFile,
-    "utf-8"
+  const localesMatch = routing.match(/locales:\s*\[([^\]]*)\]/);
+  if (!localesMatch) {
+    throw new CliError("Unable to locate routing locales.", {
+      code: "CONFIG_NOT_FOUND",
+      scope: "project",
+      path: "src/lib/i18n/routing.ts"
+    });
+  }
+  const routingLocales = localesMatch[1].split(",").map((value) => value.trim().replace(/["']/g, "")).filter(Boolean);
+  const registry = await context.fs.readText(registryFile);
+  const registryMatch = registry.match(
+    /const messages = \{([^}]*)\} as const;/
   );
-  const defaultImportPrefix = `./${defaultLocale}/`;
-  if (!defaultAggregatorContent.includes(defaultImportPrefix)) {
-    throw new Error(
-      `Default locale aggregator does not import from ${defaultImportPrefix}`
-    );
+  if (!registryMatch) {
+    throw new CliError("Unable to locate the typed messages registry.", {
+      code: "CONFIG_NOT_FOUND",
+      scope: "project",
+      path: "src/lib/i18n/messages.ts"
+    });
+  }
+  const registeredLocales = registryMatch[1].split(",").map((value) => value.trim()).filter(Boolean);
+  const targetDirectory = join4(messagesRoot, locale);
+  const targetAggregator = join4(messagesRoot, `${locale}.ts`);
+  const targetAggregatorExists = context.fs.exists(targetAggregator);
+  const targetAggregatorContent = targetAggregatorExists ? await context.fs.readText(targetAggregator) : "";
+  const state = {
+    directory: context.fs.exists(targetDirectory),
+    aggregator: targetAggregatorExists,
+    aggregatorImportsLocale: targetAggregatorContent.includes(`./${locale}/`),
+    routing: routingLocales.includes(locale),
+    registry: registeredLocales.includes(locale),
+    registryImport: new RegExp(
+      `import\\s+${locale}\\s+from\\s+["']\\.\\.\\/\\.\\.\\/\\.\\.\\/messages\\/${locale}["'];`
+    ).test(registry)
+  };
+  const present = Object.values(state).filter(Boolean).length;
+  const gateway = new MutationGateway(context, context.cwd);
+  const missingLocaleFiles = state.directory ? sourceFiles.filter(
+    (relative) => !context.fs.exists(join4(targetDirectory, relative))
+  ) : sourceFiles;
+  if (present === Object.keys(state).length && missingLocaleFiles.length === 0) {
+    gateway.unchanged(targetDirectory, {
+      role: "locale-directory",
+      resource: "directory"
+    });
+    for (const relative of sourceFiles) {
+      gateway.unchanged(join4(targetDirectory, relative), {
+        role: relative.endsWith(".json") ? "translation-messages" : "locale-file",
+        detail: { locale, sourceLocale: defaultLocale }
+      });
+    }
+    gateway.unchanged(targetAggregator, { role: "locale-aggregator" });
+    gateway.unchanged(routingFile, { role: "i18n-routing" });
+    gateway.unchanged(registryFile, { role: "messages-registry" });
+    return commandResult(context, {
+      command: "addlanguage",
+      summary: `Locale "${locale}" is already fully configured.`,
+      projectRoot: context.cwd
+    });
   }
-  const nextAggregatorContent = defaultAggregatorContent.replaceAll(
-    defaultImportPrefix,
+  if (present > 0 || missingLocaleFiles.length < sourceFiles.length) {
+    throw new CliError(`Locale ${locale} is only partially configured.`, {
+      code: "INCONSISTENT_LOCALE",
+      scope: "project",
+      path: `messages/${locale}`,
+      hint: `Observed state: ${JSON.stringify({ ...state, missingLocaleFiles })}.`
+    });
+  }
+  const nextAggregator = defaultAggregator.replaceAll(
+    importPrefix,
     `./${locale}/`
   );
-  const messagesRegistryContent = await readFile5(messagesRegistryFile, "utf-8");
-  const registryMatch = messagesRegistryContent.match(
-    /const messages = \{([^}]*)\} as const;/
+  const nextRouting = routing.replace(
+    /locales:\s*\[[^\]]*\]/,
+    `locales: [${[...routingLocales, locale].map((value) => `"${value}"`).join(", ")}]`
   );
-  if (!registryMatch) {
-    throw new Error("Unable to locate the typed messages registry.");
-  }
-  const registeredLocales = registryMatch[1].split(",").map((item) => item.trim()).filter(Boolean);
-  if (registeredLocales.includes(locale)) {
-    throw new Error(`Locale ${locale} already exists in messages registry.`);
-  }
-  const registryDeclaration = `const messages = { ${[
-    ...registeredLocales,
-    locale
-  ].join(", ")} } as const;`;
-  const declarationIndex = messagesRegistryContent.indexOf("const messages =");
-  const nextMessagesRegistryContent = messagesRegistryContent.slice(0, declarationIndex) + `import ${locale} from "../../../messages/${locale}";
+  const declarationIndex = registry.indexOf("const messages =");
+  const nextRegistry = registry.slice(0, declarationIndex) + `import ${locale} from "../../../messages/${locale}";
 
-` + messagesRegistryContent.slice(declarationIndex).replace(/const messages = \{[^}]*\} as const;/, registryDeclaration);
-  await cp(join4(messagesPath, defaultLocale), join4(messagesPath, locale), {
-    recursive: true
-  });
-  console.log(`\u{1F4C4} Directory created: ${join4(messagesPath, locale)}`);
-  await writeFile4(join4(messagesPath, `${locale}.ts`), nextAggregatorContent);
-  console.log(`\u{1F4C4} File created: ${join4(messagesPath, `${locale}.ts`)}`);
-  await writeFile4(messagesRegistryFile, nextMessagesRegistryContent);
-  console.log(`\u{1F4C4} File updated: ${messagesRegistryFile}`);
-  await writeFile4(routingFile, nextRoutingContent);
-  console.log(`\u{1F4C4} File updated: ${routingFile}`);
-  console.log(
-    `\u2705 Locale "${locale}" added and copied from default locale "${defaultLocale}".`
+` + registry.slice(declarationIndex).replace(
+    /const messages = \{[^}]*\} as const;/,
+    `const messages = { ${[...registeredLocales, locale].join(", ")} } as const;`
   );
-}
+  await assertSafeTarget(context.cwd, targetDirectory, context.fs);
+  await gateway.mkdir(targetDirectory, {
+    role: "locale-directory",
+    resource: "directory",
+    detail: { locale, sourceLocale: defaultLocale }
+  });
+  for (const relative of sourceFiles) {
+    const source = join4(sourceDirectory, relative);
+    const target = join4(targetDirectory, relative);
+    await gateway.copy(source, target, {
+      role: relative.endsWith(".json") ? "translation-messages" : "locale-file",
+      source: { scope: "project", path: gateway.path(source) },
+      detail: { locale, sourceLocale: defaultLocale }
+    });
+  }
+  await gateway.write(targetAggregator, nextAggregator, {
+    role: "locale-aggregator"
+  });
+  await gateway.write(registryFile, nextRegistry, {
+    role: "messages-registry"
+  });
+  await gateway.write(routingFile, nextRouting, { role: "i18n-routing" });
+  const translationPaths = sourceFiles.filter((relative) => relative.endsWith(".json")).map((relative) => ({
+    scope: "project",
+    path: gateway.path(join4(targetDirectory, relative))
+  }));
+  return commandResult(context, {
+    command: "addlanguage",
+    summary: `Added locale "${locale}" by copying ${sourceFiles.length} files from "${defaultLocale}".`,
+    projectRoot: context.cwd,
+    nextSteps: [
+      {
+        kind: "translate",
+        required: true,
+        message: `Translate every copied message from ${defaultLocale} to ${locale}; the copied text is not ready for delivery.`,
+        paths: translationPaths
+      },
+      {
+        kind: "run-checks",
+        required: true,
+        message: "Run the project checks.",
+        paths: [],
+        commands: ["bun run check", "npm run check", "pnpm run check"]
+      }
+    ]
+  });
+};
 
 // src/lib/addLib.ts
 import { join as join5 } from "path";
-import { mkdir as mkdir4, readFile as readFile6, writeFile as writeFile5 } from "fs/promises";
-import prompts5 from "prompts";
-import { existsSync as existsSync6 } from "fs";
-async function addLib(args, cwd = process.cwd()) {
+var addLib = async (args, context) => {
   let libArg = args[1];
   if (!libArg || libArg.startsWith("-")) {
-    const response = await prompts5.prompt({
+    if (context.outputMode === "json") {
+      throw new CliError("Library name is required in JSON mode.", {
+        code: "INTERACTIVE_INPUT_REQUIRED",
+        hint: "Pass library or library.module after addlib."
+      });
+    }
+    const response = await context.prompt({
       type: "text",
       name: "libArg",
-      message: "\u{1F4E6} Lib name to add:",
-      validate: (name) => name ? true : "Lib name is required"
+      message: "Library name to add:",
+      validate: (name) => name ? true : "Library name is required"
     });
-    libArg = response.libArg;
-  }
-  const libSegments = parseLogicalName(libArg, "library name");
-  let libName = libArg;
-  let fileName = null;
-  if (libSegments.length === 2) {
-    [libName, fileName] = libSegments;
-  } else if (libSegments.length > 2) {
-    throw new Error("Libraries currently support exactly library.module.");
+    libArg = String(response.libArg ?? "");
+    if (!libArg) {
+      context.operations.record({
+        action: "cancelled",
+        resource: "command",
+        role: "library-creation",
+        scope: "project",
+        path: "."
+      });
+      return commandResult(context, {
+        command: "addlib",
+        summary: "Library creation was cancelled.",
+        projectRoot: context.cwd,
+        status: "cancelled"
+      });
+    }
   }
-  const config = await loadConfig(cwd);
-  if (!config) {
-    console.error(
-      "\u274C Configuration file cnp.config.json not found. Run this command from the project root."
-    );
-    return;
+  const segments = parseLogicalName(libArg, "library name");
+  if (segments.length > 2) {
+    throw new CliError("Libraries support exactly library or library.module.", {
+      code: "INVALID_ARGUMENT"
+    });
   }
-  const libDir = join5(cwd, "src", "lib", libName);
-  await assertSafeTarget(cwd, libDir);
-  if (!existsSync6(libDir)) {
-    await mkdir4(libDir, { recursive: true });
+  const [libName, fileName] = segments;
+  if (!await loadConfig(context)) {
+    throw new CliError("Configuration file cnp.config.json was not found.", {
+      code: "CONFIG_NOT_FOUND",
+      hint: "Run this command from the generated project root."
+    });
   }
-  const templateDir = join5(
-    resolvePackageRoot(import.meta.url),
-    "templates",
-    "Lib"
-  );
+  const libDir = join5(context.cwd, "src", "lib", libName);
+  await assertSafeTarget(context.cwd, libDir, context.fs);
+  const gateway = new MutationGateway(context, context.cwd);
+  const templateDir = join5(context.packageRoot, "templates", "Lib");
   const indexTemplate = join5(templateDir, "index.ts");
-  const fileTemplate = join5(templateDir, "item.ts");
+  const itemTemplate = join5(templateDir, "item.ts");
+  if (!context.fs.exists(indexTemplate) || fileName && !context.fs.exists(itemTemplate)) {
+    throw new CliError("Required library template files were not found.", {
+      code: "TEMPLATE_MISSING",
+      scope: "package",
+      path: "templates/Lib"
+    });
+  }
+  await gateway.mkdir(libDir, {
+    role: "library-directory",
+    resource: "directory"
+  });
   const indexPath = join5(libDir, "index.ts");
-  if (!existsSync6(indexPath)) {
-    if (existsSync6(indexTemplate)) {
-      const content = await readFile6(indexTemplate, "utf-8");
-      await writeFile5(indexPath, content);
-    } else {
-      await writeFile5(indexPath, "export {}\n");
-    }
-    console.log(`\u{1F4C4} File created: ${indexPath}`);
+  if (!context.fs.exists(indexPath)) {
+    await gateway.write(indexPath, await context.fs.readText(indexTemplate), {
+      role: "library-index"
+    });
   }
+  let moduleAction;
   if (fileName) {
-    const filePath = join5(libDir, `${fileName}.ts`);
-    if (!existsSync6(filePath)) {
-      if (existsSync6(fileTemplate)) {
-        let content = await readFile6(fileTemplate, "utf-8");
-        content = content.replace(/template/g, fileName).replace(/Template/g, capitalize(fileName));
-        await writeFile5(filePath, content);
-      } else {
-        await writeFile5(
-          filePath,
-          `export function ${fileName}() {
-  // TODO: implement
-}
-`
-        );
-      }
-      console.log(`\u{1F4C4} File created: ${filePath}`);
-    }
-    let indexContent = await readFile6(indexPath, "utf-8");
-    const importLine = `import { ${fileName} } from "./${fileName}";`;
+    const moduleIdentifier = toIdentifier(fileName);
+    const modulePath = join5(libDir, `${fileName}.ts`);
+    const moduleContent = (await context.fs.readText(itemTemplate)).replace(/template/g, moduleIdentifier).replace(/Template/g, capitalize(moduleIdentifier));
+    moduleAction = await gateway.write(modulePath, moduleContent, {
+      role: "library-module",
+      preserveExisting: true
+    });
+    const currentIndex = await context.fs.readText(indexPath);
+    const importLine = `import { ${moduleIdentifier} } from "./${fileName}";`;
     const importRegex = new RegExp(
-      `import\\s*{\\s*${fileName}\\s*}\\s*from\\s*"\\./${fileName}";`
+      `import\\s*{\\s*${moduleIdentifier}\\s*}\\s*from\\s*["']\\./${fileName}["'];`
     );
     const exportRegex = /export\s*{([^}]*)}/m;
-    const imports = [];
-    const exportsSet = [];
-    for (const line of indexContent.split("\n")) {
-      if (line.startsWith("import")) {
-        imports.push(line);
-      } else if (line.startsWith("export")) {
-        const match = line.match(exportRegex);
-        if (match && match[1]) {
-          exportsSet.push(
-            ...match[1].split(",").map((s) => s.trim()).filter(Boolean)
-          );
-        }
-      }
-    }
-    if (!imports.some((l) => importRegex.test(l))) {
+    const imports = currentIndex.split("\n").filter((line) => line.startsWith("import"));
+    const exportMatch = currentIndex.match(exportRegex);
+    const exportsSet = (exportMatch?.[1] ?? "").split(",").map((item) => item.trim()).filter(Boolean);
+    if (!imports.some((line) => importRegex.test(line)))
       imports.push(importLine);
-    }
-    if (!exportsSet.includes(fileName)) {
-      exportsSet.push(fileName);
-    }
-    indexContent = imports.join("\n") + "\n\nexport { " + exportsSet.join(", ") + " };\n";
-    await writeFile5(indexPath, indexContent);
-    console.log(`\u270F\uFE0F Updated index: ${indexPath}`);
+    if (!exportsSet.includes(moduleIdentifier))
+      exportsSet.push(moduleIdentifier);
+    const nextIndex = `${imports.join("\n")}
+
+export { ${exportsSet.join(", ")} };
+`;
+    await gateway.write(indexPath, nextIndex, { role: "library-index" });
+  } else if (context.fs.exists(indexPath)) {
+    gateway.unchanged(indexPath, { role: "library-index" });
   }
-  console.log(
-    `\u2705 Lib "${libName}"${fileName ? ` with module ${fileName}` : ""} added.`
+  const mutated = context.operations.snapshot().some(
+    (event) => ["created", "updated", "copied", "deleted"].includes(event.action)
   );
-}
+  const nextSteps = [];
+  if (fileName && moduleAction !== "unchanged") {
+    nextSteps.push({
+      kind: "review",
+      required: true,
+      message: "Implement and review the generated library module.",
+      paths: [
+        {
+          scope: "project",
+          path: gateway.path(join5(libDir, `${fileName}.ts`))
+        }
+      ]
+    });
+  }
+  if (mutated) {
+    nextSteps.push({
+      kind: "run-checks",
+      required: true,
+      message: "Run the project checks.",
+      paths: [],
+      commands: ["bun run check", "npm run check", "pnpm run check"]
+    });
+  }
+  return commandResult(context, {
+    command: "addlib",
+    summary: mutated ? `Added library "${libName}"${fileName ? ` with module "${fileName}"` : ""}.` : `Library "${libName}"${fileName ? ` and module "${fileName}"` : ""} already exist and were preserved.`,
+    projectRoot: context.cwd,
+    nextSteps
+  });
+};
 
 // src/lib/addPage.ts
 import { join as join6 } from "path";
-import { mkdir as mkdir5, readFile as readFile7, writeFile as writeFile6, readdir as readdir4 } from "fs/promises";
-import prompts6 from "prompts";
-import { existsSync as existsSync7, statSync as statSync2 } from "fs";
+var LONG_FLAGS = [
+  "layout",
+  "page",
+  "loading",
+  "not-found",
+  "error",
+  "global-error",
+  "route",
+  "template",
+  "default"
+];
+var SHORT_FLAGS = {
+  L: "layout",
+  P: "page",
+  l: "loading",
+  n: "not-found",
+  e: "error",
+  g: "global-error",
+  r: "route",
+  t: "template",
+  d: "default"
+};
 function registerMessagesFile(content, locale, fileName) {
   const importPath = `./${locale}/${fileName}.json`;
   if (content.includes(importPath)) return content;
   const declarationIndex = content.indexOf("const messages =");
   const registryMatch = content.match(/const messages = \{([\s\S]*?)\n\};/);
-  if (declarationIndex === -1 || !registryMatch) {
-    throw new Error(
-      `Unable to register ${fileName}.json in messages/${locale}.ts`
+  if (declarationIndex < 0 || !registryMatch) {
+    throw new CliError(
+      `Unable to register ${fileName}.json in messages/${locale}.ts.`,
+      {
+        code: "CONFIG_NOT_FOUND",
+        scope: "project",
+        path: `messages/${locale}.ts`
+      }
     );
   }
-  const importStatement = `import ${fileName} from "${importPath}";
+  const identifier = toIdentifier(fileName);
+  const importStatement = `import ${identifier} from "${importPath}";
 `;
   const nextRegistry = registryMatch[0].replace(
     /\n\};$/,
     `
-  ${fileName},
+  ${identifier},
 };`
   );
   return content.slice(0, declarationIndex) + importStatement + content.slice(declarationIndex).replace(registryMatch[0], nextRegistry);
 }
-async function addPage(args, cwd = process.cwd()) {
-  let pageName = args[1];
-  if (!pageName || pageName.startsWith("-")) {
-    const response = await prompts6.prompt({
+function selectedFlags(args) {
+  const selected = /* @__PURE__ */ new Set();
+  const optionArguments = args.slice(2).filter((argument) => argument.startsWith("-"));
+  if (optionArguments.length === 0)
+    return /* @__PURE__ */ new Set(["layout", "page", "loading"]);
+  for (const argument of optionArguments) {
+    if (argument.startsWith("--")) {
+      const flag = argument.slice(2);
+      if (!LONG_FLAGS.includes(flag)) {
+        throw new CliError(`Unknown addpage option: ${argument}.`, {
+          code: "INVALID_ARGUMENT"
+        });
+      }
+      selected.add(flag);
+      continue;
+    }
+    for (const character of argument.slice(1)) {
+      const flag = SHORT_FLAGS[character];
+      if (!flag) {
+        throw new CliError(`Unknown addpage short option: -${character}.`, {
+          code: "INVALID_ARGUMENT"
+        });
+      }
+      selected.add(flag);
+    }
+  }
+  return selected;
+}
+var addPage = async (args, context) => {
+  let logicalName = args[1];
+  if (!logicalName || logicalName.startsWith("-")) {
+    if (context.outputMode === "json") {
+      throw new CliError("Page name is required in JSON mode.", {
+        code: "INTERACTIVE_INPUT_REQUIRED",
+        hint: "Pass a simple or Parent.Child page name after addpage."
+      });
+    }
+    const response = await context.prompt({
       type: "text",
       name: "pageName",
-      message: "\u{1F4DD} Page name to add:",
+      message: "Page name to add:",
       validate: (name) => name ? true : "Page name is required"
     });
-    pageName = response.pageName;
-  }
-  const pageSegments = parseLogicalName(pageName, "page name");
-  let parentName = null;
-  let childName = null;
-  if (pageSegments.length === 2) {
-    [parentName, childName] = pageSegments;
-  } else if (pageSegments.length > 2) {
-    throw new Error("Nested pages currently support exactly Parent.Child.");
-  }
-  let shortFlags = args.find((arg) => /^-[A-Za-z]+$/.test(arg));
-  const longFlags = new Set(args.filter((a) => a.startsWith("--")));
-  const flags = /* @__PURE__ */ new Set();
-  if (!shortFlags && Array.from(longFlags).length === 0) {
-    shortFlags = "-LPl";
-  }
-  if (shortFlags) {
-    for (const char of shortFlags.slice(1)) {
-      switch (char) {
-        case "L":
-          flags.add("layout");
-          break;
-        case "P":
-          flags.add("page");
-          break;
-        case "l":
-          flags.add("loading");
-          break;
-        case "n":
-          flags.add("not-found");
-          break;
-        case "e":
-          flags.add("error");
-          break;
-        case "g":
-          flags.add("global-error");
-          break;
-        case "r":
-          flags.add("route");
-          break;
-        case "t":
-          flags.add("template");
-          break;
-        case "d":
-          flags.add("default");
-          break;
-      }
+    logicalName = String(response.pageName ?? "");
+    if (!logicalName) {
+      context.operations.record({
+        action: "cancelled",
+        resource: "command",
+        role: "page-creation",
+        scope: "project",
+        path: "."
+      });
+      return commandResult(context, {
+        command: "addpage",
+        summary: "Page creation was cancelled.",
+        projectRoot: context.cwd,
+        status: "cancelled"
+      });
     }
   }
-  for (const flag of [
-    "layout",
-    "page",
-    "loading",
-    "not-found",
-    "error",
-    "global-error",
-    "route",
-    "template",
-    "default"
-  ]) {
-    if (longFlags.has("--" + flag)) flags.add(flag);
+  const pageSegments = parseLogicalName(logicalName, "page name");
+  if (pageSegments.length > 2) {
+    throw new CliError("Nested pages support exactly Parent.Child.", {
+      code: "INVALID_ARGUMENT"
+    });
   }
-  const config = await loadConfig(cwd);
+  const flags = selectedFlags(args);
+  const config = await loadConfig(context);
   if (!config) {
-    console.error(
-      "\u274C Configuration file cnp.config.json not found. Run this command from the project root."
-    );
-    return;
+    throw new CliError("Configuration file cnp.config.json was not found.", {
+      code: "CONFIG_NOT_FOUND",
+      hint: "Run this command from the generated project root."
+    });
   }
-  const useI18n = !!config.useI18n;
+  const useI18n = Boolean(config.useI18n);
   const aliasPrefix = configuredAliasPrefix(config);
-  const srcSegments = ["src", "app"];
-  if (useI18n) srcSegments.push("[locale]");
-  const srcPath = join6(cwd, ...srcSegments);
-  if (!existsSync7(srcPath)) {
-    console.error(`\u274C Expected directory not found: ${srcPath}`);
-    return;
-  }
-  let messagesPath = null;
-  let locales = [];
-  if (useI18n) {
-    messagesPath = join6(cwd, "messages");
-    if (!existsSync7(messagesPath)) {
-      console.error(
-        "\u274C Messages directory missing. Ensure i18n was configured."
-      );
-      return;
-    }
-    const entries = await readdir4(messagesPath, { withFileTypes: true });
-    locales = entries.filter((e) => e.isDirectory()).map((e) => e.name);
-  }
-  const templatePath = join6(
-    resolvePackageRoot(import.meta.url),
-    "templates",
-    "Page"
+  const appRoot = join6(
+    context.cwd,
+    "src",
+    "app",
+    ...useI18n ? ["[locale]"] : []
   );
-  let uiPageDir, localePagePath, jsonFileName;
-  if (parentName && childName) {
-    uiPageDir = join6(cwd, "src", "ui", parentName, childName);
-    localePagePath = join6(srcPath, parentName, childName);
-    jsonFileName = parentName;
-  } else {
-    uiPageDir = join6(cwd, "src", "ui", pageName);
-    localePagePath = join6(srcPath, pageName);
-    jsonFileName = pageName;
-  }
-  await assertSafeTarget(cwd, uiPageDir);
-  await assertSafeTarget(cwd, localePagePath);
-  if (!existsSync7(uiPageDir)) {
-    await mkdir5(uiPageDir, { recursive: true });
-  }
-  const uiPageFile = join6(uiPageDir, "page-ui.tsx");
-  const uiPageTemplate = join6(templatePath, "page-ui.tsx");
-  if (existsSync7(uiPageTemplate)) {
-    let uiContent = await readFile7(uiPageTemplate, "utf-8");
-    const translationNamespace = parentName && childName ? `${parentName}.${childName}` : pageName;
-    uiContent = uiContent.replace(
-      'useTranslations("template")',
-      `useTranslations("${translationNamespace}")`
-    );
-    uiContent = uiContent.replaceAll('from "@/', `from "${aliasPrefix}/`).replace(/template/g, childName || pageName).replace(/Template/g, capitalize(childName || pageName));
-    await writeFile6(uiPageFile, uiContent);
-    console.log(`\u{1F4C4} File created: ${uiPageFile}`);
-  } else {
-    console.warn(
-      "\u26A0\uFE0F Missing template file: page-ui.tsx at path:",
-      uiPageTemplate
-    );
+  if (!context.fs.exists(appRoot)) {
+    throw new CliError("The expected App Router directory was not found.", {
+      code: "CONFIG_NOT_FOUND",
+      scope: "project",
+      path: useI18n ? "src/app/[locale]" : "src/app"
+    });
   }
-  if (!existsSync7(localePagePath)) {
-    await mkdir5(localePagePath, { recursive: true });
+  const [parentName, childName] = pageSegments.length === 2 ? pageSegments : [void 0, void 0];
+  const leafName = childName ?? pageSegments[0];
+  const pageIdentifier = capitalize(toIdentifier(leafName));
+  const jsonFileName = parentName ?? leafName;
+  const uiDirectory = join6(context.cwd, "src", "ui", ...pageSegments);
+  const routeDirectory = join6(appRoot, ...pageSegments);
+  await assertSafeTarget(context.cwd, uiDirectory, context.fs);
+  await assertSafeTarget(context.cwd, routeDirectory, context.fs);
+  const templateRoot = join6(context.packageRoot, "templates", "Page");
+  const uiTemplate = join6(templateRoot, "page-ui.tsx");
+  const routeTemplates = [...flags].map((flag) => ({
+    flag,
+    source: join6(templateRoot, toFileName(flag))
+  }));
+  const messagesTemplate = join6(templateRoot, "page.json");
+  const requiredTemplates = [
+    uiTemplate,
+    ...routeTemplates.map((entry) => entry.source)
+  ];
+  if (useI18n) requiredTemplates.push(messagesTemplate);
+  const missing = requiredTemplates.find(
+    (target) => !context.fs.exists(target)
+  );
+  if (missing) {
+    throw new CliError(`Required page template was not found: ${missing}.`, {
+      code: "TEMPLATE_MISSING",
+      scope: "package",
+      path: missing.replace(`${context.packageRoot}/`, "")
+    });
   }
-  for (const flag of flags) {
-    const filename = toFileName(flag);
-    const src = join6(templatePath, filename);
-    const dst = join6(localePagePath, filename);
-    if (!existsSync7(src)) {
-      console.warn(`\u26A0\uFE0F Missing template file: ${filename} at path: ${src}`);
-      continue;
+  const translationNamespace = parentName ? `${parentName}.${childName}` : leafName;
+  const templateJson = useI18n ? JSON.parse(
+    (await context.fs.readText(messagesTemplate)).replace(/template/g, leafName).replace(/Template/g, capitalize(leafName))
+  ) : void 0;
+  const preparedLocales = [];
+  if (useI18n) {
+    const messagesRoot = join6(context.cwd, "messages");
+    if (!context.fs.exists(messagesRoot)) {
+      throw new CliError("The messages directory was not found.", {
+        code: "CONFIG_NOT_FOUND",
+        scope: "project",
+        path: "messages"
+      });
     }
-    const content = await readFile7(src, "utf-8");
-    const uiImportPath = parentName && childName ? `${parentName}/${childName}` : pageName;
-    const replaced = content.replace("@/ui/template/", `@/ui/${uiImportPath}/`).replaceAll('from "@/', `from "${aliasPrefix}/`).replace(/template/g, childName || pageName).replace(/Template/g, capitalize(childName || pageName));
-    await writeFile6(dst, replaced);
-    console.log(`\u{1F4C4} File created: ${dst}`);
-  }
-  if (useI18n && messagesPath) {
-    const jsonTemplate = join6(templatePath, "page.json");
-    if (!existsSync7(jsonTemplate)) {
-      console.warn("\u26A0\uFE0F Missing template: page.json at path:", jsonTemplate);
-    } else {
-      const content = await readFile7(jsonTemplate, "utf-8");
-      const replaced = content.replace(/template/g, childName || pageName).replace(/Template/g, capitalize(childName || pageName));
-      for (const locale of locales) {
-        const localeDir = join6(messagesPath, locale);
-        if (!existsSync7(localeDir) || !statSync2(localeDir).isDirectory())
-          continue;
-        const jsonTarget = join6(messagesPath, locale, `${jsonFileName}.json`);
-        let current = {};
-        if (existsSync7(jsonTarget)) {
-          const jsonFile = await readFile7(jsonTarget, "utf-8");
-          try {
-            current = JSON.parse(jsonFile);
-          } catch {
-            current = {};
+    const locales = (await context.fs.list(messagesRoot)).filter((entry) => entry.isDirectory).map((entry) => entry.name).sort();
+    if (locales.length === 0) {
+      throw new CliError("No locale directories were found.", {
+        code: "CONFIG_NOT_FOUND",
+        scope: "project",
+        path: "messages"
+      });
+    }
+    for (const locale of locales) {
+      const target = join6(messagesRoot, locale, `${jsonFileName}.json`);
+      const aggregator = join6(messagesRoot, `${locale}.ts`);
+      if (!context.fs.exists(aggregator)) {
+        throw new CliError(
+          `Locale aggregator messages/${locale}.ts was not found.`,
+          {
+            code: "CONFIG_NOT_FOUND",
+            scope: "project",
+            path: `messages/${locale}.ts`
           }
+        );
+      }
+      let data = {};
+      const targetExists = context.fs.exists(target);
+      if (targetExists) {
+        try {
+          data = JSON.parse(await context.fs.readText(target));
+        } catch {
+          throw new CliError(
+            `Invalid JSON in messages/${locale}/${jsonFileName}.json.`,
+            {
+              code: "FILESYSTEM_ERROR",
+              scope: "project",
+              path: `messages/${locale}/${jsonFileName}.json`
+            }
+          );
         }
-        if (parentName && childName) {
-          current[childName] = JSON.parse(replaced);
-        } else {
-          current = JSON.parse(replaced);
-        }
-        await writeFile6(jsonTarget, `${JSON.stringify(current, null, 2)}
-`);
-        console.log(`\u{1F4C4} File created: ${jsonTarget}`);
-        const localeAggregator = join6(messagesPath, `${locale}.ts`);
-        if (!existsSync7(localeAggregator)) {
-          throw new Error(`Locale aggregator not found: messages/${locale}.ts`);
-        }
-        const aggregatorContent = await readFile7(localeAggregator, "utf-8");
-        const nextAggregatorContent = registerMessagesFile(
-          aggregatorContent,
+      }
+      const messageExists = parentName ? Object.hasOwn(data, childName) : targetExists;
+      if (!messageExists) {
+        if (parentName) data[childName] = templateJson;
+        else data = templateJson;
+      }
+      const aggregatorCurrent = await context.fs.readText(aggregator);
+      preparedLocales.push({
+        locale,
+        target,
+        targetContent: messageExists ? void 0 : `${JSON.stringify(data, null, 2)}
+`,
+        messageExists,
+        aggregator,
+        aggregatorContent: registerMessagesFile(
+          aggregatorCurrent,
           locale,
           jsonFileName
-        );
-        if (nextAggregatorContent !== aggregatorContent) {
-          await writeFile6(localeAggregator, nextAggregatorContent);
-          console.log(`\u{1F4C4} File updated: ${localeAggregator}`);
-        }
+        )
+      });
+    }
+  }
+  const gateway = new MutationGateway(context, context.cwd);
+  await gateway.mkdir(uiDirectory, {
+    role: "page-ui-directory",
+    resource: "directory"
+  });
+  const uiFile = join6(uiDirectory, "page-ui.tsx");
+  const uiContent = (await context.fs.readText(uiTemplate)).replace(
+    'useTranslations("template")',
+    `useTranslations("${translationNamespace}")`
+  ).replaceAll('from "@/', `from "${aliasPrefix}/`).replace(/template/g, pageIdentifier).replace(/Template/g, pageIdentifier);
+  await gateway.write(uiFile, uiContent, {
+    role: "page-ui",
+    preserveExisting: true
+  });
+  await gateway.mkdir(routeDirectory, {
+    role: "page-route-directory",
+    resource: "directory"
+  });
+  for (const template of routeTemplates) {
+    const filename = toFileName(template.flag);
+    const target = join6(routeDirectory, filename);
+    const uiImportPath = pageSegments.join("/");
+    const content = (await context.fs.readText(template.source)).replace("@/ui/template/", `@/ui/${uiImportPath}/`).replaceAll('from "@/', `from "${aliasPrefix}/`).replace(/template/g, pageIdentifier).replace(/Template/g, pageIdentifier);
+    await gateway.write(target, content, {
+      role: `page-${template.flag}`,
+      preserveExisting: true
+    });
+  }
+  if (useI18n) {
+    for (const item of preparedLocales) {
+      if (item.messageExists) {
+        gateway.unchanged(item.target, {
+          role: "translation-messages",
+          detail: { locale: item.locale, namespace: translationNamespace }
+        });
+      } else {
+        await gateway.write(item.target, item.targetContent, {
+          role: "translation-messages",
+          detail: { locale: item.locale, namespace: translationNamespace }
+        });
       }
+      await gateway.write(item.aggregator, item.aggregatorContent, {
+        role: "locale-aggregator"
+      });
     }
   } else {
-    console.log("\u2139\uFE0F Skipping translation templates; next-intl not enabled.");
+    gateway.skipped(join6(context.cwd, "messages"), {
+      role: "translation-messages",
+      resource: "directory",
+      detail: { reason: "Internationalization is disabled." }
+    });
   }
-  console.log(
-    `\u2705 Page "${pageName}" with templates added${useI18n ? " for each locale" : ""}.`
+  const mutated = context.operations.snapshot().some(
+    (event) => ["created", "updated", "copied", "deleted"].includes(event.action)
   );
-}
+  const reviewPaths = [
+    { scope: "project", path: gateway.path(uiFile) },
+    ...routeTemplates.map((template) => ({
+      scope: "project",
+      path: gateway.path(join6(routeDirectory, toFileName(template.flag)))
+    })),
+    ...preparedLocales.map((item) => ({
+      scope: "project",
+      path: gateway.path(item.target)
+    }))
+  ];
+  return commandResult(context, {
+    command: "addpage",
+    summary: mutated ? `Added page "${logicalName}" and its missing resources.` : `Page "${logicalName}" already exists and was preserved.`,
+    projectRoot: context.cwd,
+    nextSteps: mutated ? [
+      {
+        kind: "review",
+        required: true,
+        message: "Review the generated page UI, route files and localized messages.",
+        paths: reviewPaths
+      },
+      {
+        kind: "run-checks",
+        required: true,
+        message: "Run the project checks.",
+        paths: [],
+        commands: ["bun run check", "npm run check", "pnpm run check"]
+      }
+    ] : []
+  });
+};
 
 // src/lib/addText.ts
 import { join as join7 } from "path";
-import { existsSync as existsSync8 } from "fs";
-import { readFile as readFile8, writeFile as writeFile7, readdir as readdir5 } from "fs/promises";
 function defaultText(key) {
-  return key.replace(/_/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+  return key.replace(/_/g, " ").replace(/\b\w/g, (character) => character.toUpperCase());
 }
-async function addText(args, cwd = process.cwd()) {
+var addText = async (args, context) => {
   const pathArg = args[1];
   if (!pathArg) {
-    console.error("\u274C Dot path parameter is required.");
-    return;
+    throw new CliError("Translation dot path is required.", {
+      code: "INVALID_ARGUMENT",
+      hint: "Use addtext domain.key followed by an optional value."
+    });
+  }
+  const segments = parseLogicalName(pathArg, "translation path");
+  if (segments.length < 2) {
+    throw new CliError("Translation path must contain a file and a key.", {
+      code: "INVALID_ARGUMENT"
+    });
   }
   const providedText = args.slice(2).join(" ");
-  parseLogicalName(pathArg, "translation path");
-  const config = await loadConfig(cwd);
+  const finalKey = segments.at(-1);
+  const text = providedText || defaultText(finalKey);
+  const config = await loadConfig(context);
   if (!config?.useI18n) {
-    console.error("\u274C i18n is not enabled in this project.");
-    return;
+    throw new CliError("Internationalization is not enabled in this project.", {
+      code: "I18N_DISABLED"
+    });
   }
-  const messagesPath = join7(cwd, "messages");
-  if (!existsSync8(messagesPath)) {
-    console.error("\u274C Messages directory missing. Ensure i18n was configured.");
-    return;
+  const messagesRoot = join7(context.cwd, "messages");
+  if (!context.fs.exists(messagesRoot)) {
+    throw new CliError("The messages directory was not found.", {
+      code: "CONFIG_NOT_FOUND",
+      scope: "project",
+      path: "messages"
+    });
   }
-  const entries = await readdir5(messagesPath, { withFileTypes: true });
-  const locales = entries.filter((e) => e.isDirectory()).map((e) => e.name);
-  const [fileName, ...segments] = pathArg.split(".");
-  if (!fileName || segments.length === 0) {
-    console.error("\u274C Invalid dot path provided.");
-    return;
+  const locales = (await context.fs.list(messagesRoot)).filter((entry) => entry.isDirectory).map((entry) => entry.name).sort();
+  if (locales.length === 0) {
+    throw new CliError("No locale directories were found.", {
+      code: "CONFIG_NOT_FOUND",
+      scope: "project",
+      path: "messages"
+    });
   }
-  const finalKey = segments[segments.length - 1];
-  const text = providedText || defaultText(finalKey);
+  const [fileName, ...keySegments] = segments;
+  const prepared = [];
   for (const locale of locales) {
-    const filePath = join7(messagesPath, locale, `${fileName}.json`);
-    await assertSafeTarget(cwd, filePath);
+    const file = join7(messagesRoot, locale, `${fileName}.json`);
+    await assertSafeTarget(context.cwd, file, context.fs);
+    const existed = context.fs.exists(file);
     let data = {};
-    if (existsSync8(filePath)) {
-      const raw = await readFile8(filePath, "utf-8");
+    if (existed) {
       try {
-        data = JSON.parse(raw);
-      } catch {
+        const parsed = JSON.parse(await context.fs.readText(file));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+          throw new Error("root value is not an object");
+        }
+        data = parsed;
+      } catch (error) {
+        throw new CliError(
+          `Invalid JSON in messages/${locale}/${fileName}.json.`,
+          {
+            code: "FILESYSTEM_ERROR",
+            scope: "project",
+            path: `messages/${locale}/${fileName}.json`,
+            hint: error instanceof Error ? error.message : void 0
+          }
+        );
       }
     }
     let cursor = data;
-    for (let i = 0; i < segments.length - 1; i++) {
-      const seg = segments[i];
-      if (!cursor[seg]) cursor[seg] = {};
-      cursor = cursor[seg];
+    for (const segment of keySegments.slice(0, -1)) {
+      const current = cursor[segment];
+      if (current === void 0) cursor[segment] = {};
+      else if (!current || typeof current !== "object" || Array.isArray(current)) {
+        throw new CliError(
+          `Translation segment "${segment}" is not an object in ${locale}.`,
+          {
+            code: "INVALID_ARGUMENT",
+            scope: "project",
+            path: `messages/${locale}/${fileName}.json`
+          }
+        );
+      }
+      cursor = cursor[segment];
     }
+    const previous = cursor[finalKey];
     cursor[finalKey] = text;
-    await writeFile7(filePath, JSON.stringify(data, null, 2));
-    console.log(`\u{1F4C4} File updated: ${filePath}`);
+    prepared.push({
+      locale,
+      file,
+      data,
+      replaced: previous !== void 0 && previous !== text
+    });
   }
-  console.log(`\u2705 Text added at path "${pathArg}" with value "${text}".`);
-}
+  const gateway = new MutationGateway(context, context.cwd);
+  for (const item of prepared) {
+    await gateway.write(item.file, `${JSON.stringify(item.data, null, 2)}
+`, {
+      role: "translation-messages",
+      detail: {
+        locale: item.locale,
+        key: pathArg,
+        replaced: item.replaced
+      }
+    });
+  }
+  const mutated = context.operations.snapshot().some((event) => event.action === "created" || event.action === "updated");
+  const nextSteps = mutated ? [
+    ...locales.length > 1 ? [
+      {
+        kind: "translate",
+        required: true,
+        message: "Review the value in every locale; the same text was written to all locale files.",
+        paths: prepared.map((item) => ({
+          scope: "project",
+          path: gateway.path(item.file)
+        }))
+      }
+    ] : [],
+    {
+      kind: "run-checks",
+      required: true,
+      message: "Run the project checks.",
+      paths: [],
+      commands: ["bun run check", "npm run check", "pnpm run check"]
+    }
+  ] : [];
+  return commandResult(context, {
+    command: "addtext",
+    summary: mutated ? `Set translation "${pathArg}" to "${text}" in ${locales.length} locale files.` : `Translation "${pathArg}" already has value "${text}" in every locale.`,
+    projectRoot: context.cwd,
+    nextSteps
+  });
+};
 
 // src/lib/rmPage.ts
-import { existsSync as existsSync9 } from "fs";
-import { readFile as readFile9, readdir as readdir6, rm, writeFile as writeFile8 } from "fs/promises";
-import path6 from "path";
-async function removeMessages(projectRoot, candidate, terminal) {
-  const messagesRoot = resolveInside(projectRoot, "messages");
-  let locales;
-  try {
-    locales = (await readdir6(messagesRoot, { withFileTypes: true })).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
-  } catch {
-    return;
-  }
-  for (const locale of locales) {
-    const target = resolveInside(
-      projectRoot,
-      "messages",
-      locale,
-      `${candidate.routeSegments[0]}.json`
+import path7 from "path";
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function unregisterMessagesFile(content, locale, fileName) {
+  const identifier = toIdentifier(fileName);
+  const escapedIdentifier = escapeRegExp(identifier);
+  const escapedPath = escapeRegExp(`./${locale}/${fileName}.json`);
+  const importPattern = new RegExp(
+    `^import\\s+${escapedIdentifier}\\s+from\\s+["']${escapedPath}["'];?\\r?\\n?`,
+    "m"
+  );
+  const propertyPattern = new RegExp(
+    `^\\s*${escapedIdentifier},\\s*\\r?\\n?`,
+    "m"
+  );
+  const hasImport = importPattern.test(content);
+  const hasProperty = propertyPattern.test(content);
+  if (hasImport !== hasProperty) {
+    throw new CliError(
+      `Locale aggregator messages/${locale}.ts is inconsistent for ${fileName}.json.`,
+      {
+        code: "INCONSISTENT_LOCALE",
+        scope: "project",
+        path: `messages/${locale}.ts`
+      }
     );
-    if (!existsSync9(target)) continue;
-    if (candidate.messageKey) {
-      const data = JSON.parse(await readFile9(target, "utf8"));
-      delete data[candidate.messageKey];
-      await writeFile8(target, `${JSON.stringify(data, null, 2)}
-`);
-    } else {
-      await rm(target);
-    }
-    terminal.log(`\u{1F5D1}\uFE0F Deleted messages for ${candidate.logicalName}: ${target}`);
   }
+  if (!hasImport) return { content, changed: false };
+  return {
+    content: content.replace(importPattern, "").replace(propertyPattern, ""),
+    changed: true
+  };
 }
-async function rmPage(args, cwd = process.cwd(), prompt, terminal = console) {
-  const candidates = await discoverPages(cwd);
+var rmPage = async (args, context) => {
+  const candidates = await discoverPages(context.cwd, context.fs);
   let logicalName = args[1];
   if (!logicalName || logicalName.startsWith("-")) {
-    if (!prompt)
-      throw new CliError("A page name is required in non-interactive mode.");
-    const selected = await prompt([
+    if (context.outputMode === "json") {
+      throw new CliError("Page name is required in JSON mode.", {
+        code: "INTERACTIVE_INPUT_REQUIRED",
+        hint: "Pass a page name returned by completion after rmpage."
+      });
+    }
+    const selected = await context.prompt([
       {
         type: "autocomplete",
         name: "page",
-        message: "\u{1F5D1}\uFE0F Page to remove:",
+        message: "Page to remove:",
         choices: candidates.map((candidate2) => ({
-          title: candidate2.logicalName.replaceAll(".", " \u203A "),
+          title: candidate2.logicalName.replaceAll(".", " > "),
           value: candidate2.logicalName
         }))
       },
@@ -1179,8 +1896,19 @@ async function rmPage(args, cwd = process.cwd(), prompt, terminal = console) {
       }
     ]);
     if (!selected.confirm) {
-      terminal.log("Page deletion cancelled.");
-      return;
+      context.operations.record({
+        action: "cancelled",
+        resource: "command",
+        role: "page-removal",
+        scope: "project",
+        path: "."
+      });
+      return commandResult(context, {
+        command: "rmpage",
+        summary: "Page deletion was cancelled.",
+        projectRoot: context.cwd,
+        status: "cancelled"
+      });
     }
     logicalName = String(selected.page ?? "");
   }
@@ -1188,77 +1916,161 @@ async function rmPage(args, cwd = process.cwd(), prompt, terminal = console) {
   const candidate = candidates.find(
     (entry) => entry.logicalName === logicalName
   );
-  if (!candidate) throw new CliError(`Page not found: ${logicalName}`);
-  await removeMessages(cwd, candidate, terminal);
-  for (const target of [candidate.uiDirectory, candidate.routeDirectory]) {
-    const safeTarget = resolveInside(cwd, path6.relative(cwd, target));
-    if (existsSync9(safeTarget)) {
-      await rm(safeTarget, { recursive: true, force: false });
-      terminal.log(`\u{1F5D1}\uFE0F Deleted: ${safeTarget}`);
+  if (!candidate) {
+    throw new CliError(`Page not found: ${logicalName}.`, {
+      code: "TARGET_NOT_FOUND",
+      scope: "project",
+      path: logicalName.replaceAll(".", "/")
+    });
+  }
+  const messagesRoot = resolveInside(context.cwd, "messages");
+  const preparedMessages = [];
+  const preparedAggregators = [];
+  if (context.fs.exists(messagesRoot)) {
+    const locales = (await context.fs.list(messagesRoot)).filter((entry) => entry.isDirectory).map((entry) => entry.name).sort();
+    for (const locale of locales) {
+      const target = resolveInside(
+        context.cwd,
+        "messages",
+        locale,
+        `${candidate.routeSegments[0]}.json`
+      );
+      if (!candidate.messageKey) {
+        const aggregator = resolveInside(
+          context.cwd,
+          "messages",
+          `${locale}.ts`
+        );
+        if (!context.fs.exists(aggregator)) {
+          throw new CliError(
+            `Locale aggregator messages/${locale}.ts was not found.`,
+            {
+              code: "CONFIG_NOT_FOUND",
+              scope: "project",
+              path: `messages/${locale}.ts`
+            }
+          );
+        }
+        const nextAggregator = unregisterMessagesFile(
+          await context.fs.readText(aggregator),
+          locale,
+          candidate.routeSegments[0]
+        );
+        preparedMessages.push({
+          target,
+          keyPresent: context.fs.exists(target)
+        });
+        preparedAggregators.push({
+          target: aggregator,
+          ...nextAggregator
+        });
+        continue;
+      }
+      if (!context.fs.exists(target)) continue;
+      let data;
+      try {
+        data = JSON.parse(await context.fs.readText(target));
+      } catch {
+        throw new CliError(
+          `Invalid JSON prevents removal from ${path7.relative(context.cwd, target)}.`,
+          {
+            code: "FILESYSTEM_ERROR",
+            scope: "project",
+            path: path7.relative(context.cwd, target)
+          }
+        );
+      }
+      const keyPresent = Object.hasOwn(data, candidate.messageKey);
+      if (keyPresent) delete data[candidate.messageKey];
+      preparedMessages.push({
+        target,
+        keyPresent,
+        content: `${JSON.stringify(data, null, 2)}
+`
+      });
     }
   }
-  terminal.log(`\u2705 Page "${logicalName}" deleted.`);
-}
+  const gateway = new MutationGateway(context, context.cwd);
+  for (const prepared of preparedMessages) {
+    if (!candidate.messageKey) {
+      await gateway.remove(prepared.target, { role: "translation-messages" });
+    } else if (prepared.keyPresent) {
+      await gateway.write(prepared.target, prepared.content, {
+        role: "translation-messages",
+        detail: { removedKey: candidate.messageKey }
+      });
+    } else {
+      gateway.unchanged(prepared.target, {
+        role: "translation-messages",
+        detail: { missingKey: candidate.messageKey }
+      });
+    }
+  }
+  for (const prepared of preparedAggregators) {
+    if (prepared.changed) {
+      await gateway.write(prepared.target, prepared.content, {
+        role: "locale-aggregator"
+      });
+    } else {
+      gateway.unchanged(prepared.target, { role: "locale-aggregator" });
+    }
+  }
+  await gateway.remove(
+    candidate.uiDirectory,
+    {
+      role: "page-ui",
+      resource: "directory"
+    },
+    { recursive: true, force: false }
+  );
+  await gateway.remove(
+    candidate.routeDirectory,
+    {
+      role: "page-route",
+      resource: "directory"
+    },
+    { recursive: true, force: false }
+  );
+  const mutated = context.operations.snapshot().some((event) => event.action === "deleted" || event.action === "updated");
+  return commandResult(context, {
+    command: "rmpage",
+    summary: mutated ? `Deleted page "${logicalName}" and its associated resources.` : `No resources remained for page "${logicalName}".`,
+    projectRoot: context.cwd,
+    nextSteps: mutated ? [
+      {
+        kind: "run-checks",
+        required: true,
+        message: "Run the project checks after removing the page.",
+        paths: [],
+        commands: ["bun run check", "npm run check", "pnpm run check"]
+      }
+    ] : []
+  });
+};
 
 // src/cli/registry.ts
-function legacyHandler(command) {
-  return async (args, context) => {
-    await command(args, context.cwd);
-    return success();
-  };
-}
 function createCommandRegistry() {
   return /* @__PURE__ */ new Map([
-    ["addcomponent", legacyHandler(addComponent)],
-    ["addpage", legacyHandler(addPage)],
-    ["addlib", legacyHandler(addLib)],
-    ["addapi", legacyHandler(addApi)],
-    ["addlanguage", legacyHandler(addLanguage)],
-    ["addtext", legacyHandler(addText)],
-    [
-      "rmpage",
-      async (args, context) => {
-        await rmPage(args, context.cwd, context.prompt, context.terminal);
-        return success();
-      }
-    ]
+    ["addcomponent", addComponent],
+    ["addpage", addPage],
+    ["addlib", addLib],
+    ["addapi", addApi],
+    ["addlanguage", addLanguage],
+    ["addtext", addText],
+    ["rmpage", rmPage]
   ]);
 }
 
 // src/scaffold.ts
-import { mkdir as mkdir7, rm as rm2, writeFile as writeFile10 } from "fs/promises";
 import { join as join8, resolve } from "path";
-import { existsSync as existsSync10 } from "fs";
-import { fileURLToPath as fileURLToPath2 } from "url";
-
-// src/lib/helper/consoleColor.ts
-var RED = "\x1B[31m";
-var GREEN = "\x1B[32m";
-var CYAN = "\x1B[36m";
-var RESET = "\x1B[0m";
-function red(text) {
-  return RED + text + RESET;
-}
-function green(text) {
-  return GREEN + text + RESET;
-}
-function cyan(text) {
-  return CYAN + text + RESET;
-}
+import { fileURLToPath } from "url";
 
 // src/core/template-manifest.ts
-import {
-  lstat as lstat2,
-  mkdir as mkdir6,
-  readdir as readdir7,
-  readFile as readFile10,
-  writeFile as writeFile9,
-  copyFile as copyFile2
-} from "fs/promises";
-import path7 from "path";
+import path8 from "path";
 var TEMPLATE_DENY_NAMES = /* @__PURE__ */ new Set([
   ".env",
   ".git",
+  ".gitignore",
   ".agent",
   ".cursor",
   ".next",
@@ -1269,80 +2081,142 @@ var TEMPLATE_DENY_NAMES = /* @__PURE__ */ new Set([
   "test-results"
 ]);
 function isDistributableTemplatePath(relativePath) {
-  const segments = relativePath.split(path7.sep);
+  const segments = relativePath.split(path8.sep);
   return !segments.some(
-    (segment) => TEMPLATE_DENY_NAMES.has(segment) || segment.endsWith(".tsbuildinfo") || segment === ".DS_Store"
+    (segment) => TEMPLATE_DENY_NAMES.has(segment) || segment.startsWith(".env") && segment !== ".env.example" || segment.endsWith(".tsbuildinfo") || segment === ".DS_Store"
   );
 }
-async function templateManifest(root) {
+async function templateManifest(root, fs) {
   const files = [];
   async function visit(directory, relativeDirectory = "") {
-    const entries = await readdir7(directory, { withFileTypes: true });
-    entries.sort((left, right) => left.name.localeCompare(right.name));
+    const entries = await fs.list(directory);
     for (const entry of entries) {
-      const relative = path7.join(relativeDirectory, entry.name);
+      const relative = path8.join(relativeDirectory, entry.name);
       if (!isDistributableTemplatePath(relative)) continue;
-      const source = path7.join(directory, entry.name);
-      const stats = await lstat2(source);
-      if (stats.isSymbolicLink()) {
+      const source = path8.join(directory, entry.name);
+      if (entry.isSymbolicLink) {
         throw new CliError(
-          `Symbolic links are forbidden in templates: ${relative}`
+          `Symbolic links are forbidden in templates: ${relative}`,
+          { code: "UNSAFE_PATH", scope: "package", path: relative }
         );
       }
-      if (stats.isDirectory()) await visit(source, relative);
-      else if (stats.isFile()) files.push(relative);
-      else throw new CliError(`Unsupported template entry: ${relative}`);
+      if (entry.isDirectory) await visit(source, relative);
+      else if (entry.isFile) files.push(relative);
+      else
+        throw new CliError(`Unsupported template entry: ${relative}`, {
+          code: "TEMPLATE_MISSING",
+          scope: "package",
+          path: relative
+        });
     }
   }
   await visit(root);
   return files;
 }
-async function copyTemplate(root, target) {
-  const manifest = await templateManifest(root);
-  await mkdir6(target, { recursive: true });
-  for (const relative of manifest) {
-    const destination = path7.join(
+async function validateScaffoldTemplate(root, fs) {
+  const manifest = await templateManifest(root, fs);
+  for (const required of [
+    "package.json",
+    "tsconfig.json",
+    ".env.example",
+    ".gitignore.template",
+    ".prettierignore",
+    "bun.lock",
+    "pnpm-workspace.yaml",
+    "vitest.config.ts",
+    path8.join("scripts", "audit.ts"),
+    path8.join("scripts", "package-manager.ts"),
+    path8.join("tests", "consumer", "validate-template.ts"),
+    path8.join(".github", "workflows", "quality.yml")
+  ]) {
+    if (!manifest.includes(required)) {
+      throw new CliError(`Required template file was not found: ${required}.`, {
+        code: "TEMPLATE_MISSING",
+        scope: "package",
+        path: `templates/Projects/default/${required}`
+      });
+    }
+  }
+  try {
+    JSON.parse(await fs.readText(path8.join(root, "package.json")));
+    const tsconfig = JSON.parse(
+      await fs.readText(path8.join(root, "tsconfig.json"))
+    );
+    if (!tsconfig.compilerOptions?.paths?.["@/*"]) throw new Error("alias");
+  } catch {
+    throw new CliError(
+      'The template manifests must be valid JSON and define the default "@/*" alias.',
+      {
+        code: "TEMPLATE_MISSING",
+        scope: "package",
+        path: "templates/Projects/default"
+      }
+    );
+  }
+  return manifest;
+}
+async function copyTemplate(root, target, context, gateway, manifest) {
+  const files = manifest ?? await templateManifest(root, context.fs);
+  for (const relative of files) {
+    const destination = path8.join(
       target,
       relative === ".gitignore.template" ? ".gitignore" : relative
     );
-    await mkdir6(path7.dirname(destination), { recursive: true });
-    await copyFile2(path7.join(root, relative), destination);
+    const source = path8.join(root, relative);
+    await gateway.copy(source, destination, {
+      role: "template-file",
+      source: { template: `Projects/default/${relative}` }
+    });
   }
-  return manifest;
+  return files;
 }
-async function customizeGeneratedProject(target, projectName, importAlias) {
-  const packagePath = path7.join(target, "package.json");
-  const packageJson = JSON.parse(await readFile10(packagePath, "utf8"));
+async function customizeGeneratedProject(target, projectName, importAlias, context, gateway) {
+  const packagePath = path8.join(target, "package.json");
+  const packageJson = JSON.parse(
+    await context.fs.readText(packagePath)
+  );
   packageJson.name = projectName.toLowerCase();
   delete packageJson.packageManager;
-  await writeFile9(packagePath, `${JSON.stringify(packageJson, null, 2)}
-`);
-  const tsconfigPath = path7.join(target, "tsconfig.json");
-  const tsconfigContent = await readFile10(tsconfigPath, "utf8");
+  await gateway.write(
+    packagePath,
+    `${JSON.stringify(packageJson, null, 2)}
+`,
+    { role: "package-manifest" }
+  );
+  const tsconfigPath = path8.join(target, "tsconfig.json");
+  const tsconfigContent = await context.fs.readText(tsconfigPath);
   const tsconfig = JSON.parse(tsconfigContent);
   if (!tsconfig.compilerOptions?.paths?.["@/*"]) {
     throw new CliError(
-      'The template tsconfig must define the default "@/*" alias.'
+      'The template tsconfig must define the default "@/*" alias.',
+      {
+        code: "TEMPLATE_MISSING",
+        scope: "package",
+        path: "templates/Projects/default/tsconfig.json"
+      }
     );
   }
-  await writeFile9(
+  await gateway.write(
     tsconfigPath,
-    tsconfigContent.replace('"@/*"', `"${importAlias}"`)
+    tsconfigContent.replace('"@/*"', `"${importAlias}"`),
+    { role: "typescript-configuration" }
   );
   if (importAlias !== "@/*") {
     const prefix = importAlias.slice(0, -2);
-    for (const relative of await templateManifest(target)) {
+    for (const relative of await templateManifest(target, context.fs)) {
       if (!/\.[cm]?[jt]sx?$/.test(relative)) continue;
-      const file = path7.join(target, relative);
-      const content = await readFile10(file, "utf8");
+      const file = path8.join(target, relative);
+      const content = await context.fs.readText(file);
       const next = content.replaceAll('from "@/', `from "${prefix}/`).replaceAll("from '@/", `from '${prefix}/`);
-      if (next !== content) await writeFile9(file, next);
+      if (next !== content) {
+        await gateway.write(file, next, { role: "import-alias-reference" });
+      }
     }
   }
 }
 
 // src/scaffold.ts
-async function scaffoldProject(options, runtime = {}) {
+async function scaffoldProject(options, runtime) {
   const requiredFeatures = [
     "useTypescript",
     "useEslint",
@@ -1356,75 +2230,120 @@ async function scaffoldProject(options, runtime = {}) {
   );
   if (unsupported.length > 0) {
     throw new CliError(
-      `The default Next.js 16 template requires: ${unsupported.join(", ")}.`
+      `The default Next.js 16 template requires: ${unsupported.join(", ")}.`,
+      { code: "INVALID_ARGUMENT" }
     );
   }
-  const cwd = runtime.cwd ?? process.cwd();
-  const terminal = runtime.terminal ?? console;
+  const { context } = runtime;
+  const cwd = context.cwd;
   const projectName = validateProjectName(options.projectName);
   const importAlias = normalizeImportAlias(
     options.customAlias === false ? "@/*" : options.importAlias || "@/*"
   );
   const targetPath = join8(cwd, projectName);
   const __dirname = new URL(".", import.meta.url);
-  const templatePath = runtime.templatePath ?? join8(fileURLToPath2(__dirname), "..", "templates", "Projects", "default");
+  const templatePath = runtime.templatePath ?? join8(fileURLToPath(__dirname), "..", "templates", "Projects", "default");
   const resolvedCwd = resolve(cwd);
   const resolvedTarget = resolve(targetPath);
   if (!resolvedTarget.startsWith(`${resolvedCwd}/`)) {
     throw new CliError(
-      "The project destination must be a child of the current directory."
+      "The project destination must be a child of the current directory.",
+      { code: "UNSAFE_PATH" }
     );
   }
-  if (existsSync10(targetPath)) {
+  const gateway = new MutationGateway(context, targetPath);
+  const manifest = await validateScaffoldTemplate(templatePath, context.fs);
+  if (context.fs.exists(targetPath)) {
     if (options.force) {
-      terminal.warn("\u26A0\uFE0F Target directory already exists, removing...");
-      await rm2(targetPath, { recursive: true, force: true });
-    } else {
-      terminal.error(
-        red("[X] Target directory already exists. Use --force to overwrite.")
+      if (context.outputMode === "human") {
+        context.terminal.warn(
+          `WARNING: --force will remove the existing project at ${targetPath}.`
+        );
+      }
+      await gateway.remove(
+        targetPath,
+        {
+          role: "existing-project",
+          resource: "project"
+        },
+        { recursive: true, force: true }
       );
+    } else {
       throw new CliError(
-        "[X] Target directory already exists. Use --force to overwrite."
+        "Target directory already exists. Use --force to overwrite it.",
+        {
+          code: "TARGET_EXISTS",
+          scope: "project",
+          path: "."
+        }
       );
     }
   }
-  try {
-    terminal.log("Creating project directory...");
-    await mkdir7(targetPath, { recursive: true });
-    terminal.log("Copying files from template...");
-    await copyTemplate(templatePath, targetPath);
-    await customizeGeneratedProject(targetPath, projectName, importAlias);
-    await writeFile10(
-      join8(targetPath, "cnp.config.json"),
-      `${JSON.stringify({ ...options, projectName, importAlias }, null, 2)}
-`
-    );
-    terminal.log("Project setup complete!");
-    terminal.log("");
-    terminal.log("To get started:");
-    terminal.log("    " + green(`cd ${options.projectName}`));
-    terminal.log("");
-    terminal.log(
-      "Then install dependencies and launch the dev server with your preferred tool:"
-    );
-    terminal.log("    " + green(`bun install && bun dev`));
-    terminal.log("    " + green(`npm install && npm run dev`));
-    terminal.log("    " + green(`pnpm install && pnpm run dev`));
-    terminal.log("");
-    terminal.log("Documentation and examples can be found at:");
-    terminal.log(
-      "    " + cyan("https://github.com/Rising-Corporation/create-next-pro-cli")
-    );
-    terminal.log(
-      "_-`'-_-'`_`'-_-'`_`'-_-'`_`'-_-'`_`'-_-'`_`'-_-'`_`'-_-'`_`'-_-'`-_"
-    );
-  } catch (err) {
-    terminal.error(red("[X] Error during project creation:"), err);
-    throw new CliError("[X] Error during project creation:");
-  }
+  await gateway.mkdir(targetPath, {
+    resource: "project",
+    role: "project-root"
+  });
+  await copyTemplate(templatePath, targetPath, context, gateway, manifest);
+  await customizeGeneratedProject(
+    targetPath,
+    projectName,
+    importAlias,
+    context,
+    gateway
+  );
+  await gateway.write(
+    join8(targetPath, "cnp.config.json"),
+    `${JSON.stringify({ ...options, projectName, importAlias }, null, 2)}
+`,
+    {
+      role: "project-configuration",
+      resource: "configuration",
+      detail: { importAlias, packageManager: "user-selected" }
+    }
+  );
+  return { projectRoot: targetPath, copiedFiles: manifest.length, importAlias };
 }
 
 // src/lib/createProject.ts
+async function createProjectFromOptions(options, context) {
+  const { projectRoot, copiedFiles, importAlias } = await scaffoldProject(
+    options,
+    {
+      context
+    }
+  );
+  return commandResult(context, {
+    command: "create",
+    summary: `Created project "${options.projectName}" with ${copiedFiles} template files and import alias ${importAlias}; no package manager was pinned.`,
+    projectRoot,
+    nextSteps: [
+      {
+        kind: "install",
+        required: true,
+        message: "Install dependencies with your preferred package manager.",
+        paths: [],
+        commands: [
+          `cd ${options.projectName} && bun install`,
+          `cd ${options.projectName} && npm install`,
+          `cd ${options.projectName} && pnpm install`
+        ]
+      },
+      {
+        kind: "run-checks",
+        required: true,
+        message: "Run the generated project checks before development.",
+        paths: [{ scope: "project", path: "package.json" }],
+        commands: ["bun run check", "npm run check", "pnpm run check"]
+      }
+    ],
+    data: {
+      projectName: options.projectName,
+      importAlias,
+      packageManager: null,
+      copiedFiles
+    }
+  });
+}
 async function createProject(nameArg, force, context) {
   const response = {
     projectName: nameArg,
@@ -1438,12 +2357,7 @@ async function createProject(nameArg, force, context) {
     importAlias: "@/*",
     force
   };
-  const terminal = context?.terminal ?? console;
-  terminal.log(`Creating project "${response.projectName}"...`);
-  await scaffoldProject(response, {
-    cwd: context?.cwd ?? process.cwd(),
-    terminal
-  });
+  return createProjectFromOptions(response, context);
 }
 
 // src/lib/createProjectWithPrompt.ts
@@ -1518,31 +2432,135 @@ async function createProjectWithPrompt(context) {
       initial: "@core/*"
     }
   ]);
+  if (!response.projectName) {
+    context.operations.record({
+      action: "cancelled",
+      resource: "command",
+      role: "project-creation",
+      scope: "project",
+      path: "."
+    });
+    return commandResult(context, {
+      command: "create",
+      summary: "Project creation was cancelled.",
+      projectRoot: context.cwd,
+      status: "cancelled"
+    });
+  }
   const options = response;
-  context.terminal.log("\nYour choices:");
-  context.terminal.log(options);
-  await scaffoldProject(options, {
-    cwd: context.cwd,
-    terminal: context.terminal
-  });
+  return createProjectFromOptions(options, context);
+}
+
+// src/runtime/node-context.ts
+import { existsSync } from "fs";
+import {
+  appendFile,
+  copyFile,
+  lstat,
+  mkdir,
+  readdir,
+  readFile,
+  rm,
+  writeFile
+} from "fs/promises";
+import os from "os";
+import path9 from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import prompts from "prompts";
+function findPackageRoot(start) {
+  let current = start;
+  while (true) {
+    const packagePath = path9.join(current, "package.json");
+    if (existsSync(packagePath)) return current;
+    const parent = path9.dirname(current);
+    if (parent === current) {
+      throw new Error(`Unable to locate package.json from ${start}`);
+    }
+    current = parent;
+  }
+}
+function resolvePackageRoot(metaUrl = import.meta.url) {
+  return findPackageRoot(path9.dirname(fileURLToPath2(metaUrl)));
+}
+function createNodeContext(overrides = {}) {
+  return {
+    argv: process.argv.slice(2),
+    cwd: process.cwd(),
+    env: process.env,
+    homeDir: os.homedir(),
+    packageRoot: resolvePackageRoot(),
+    terminal: console,
+    prompt: prompts,
+    fs: {
+      exists: existsSync,
+      readText: (target) => readFile(target, "utf8"),
+      writeText: async (target, content) => {
+        await writeFile(target, content);
+      },
+      mkdir: async (target) => {
+        await mkdir(target, { recursive: true });
+      },
+      copyFile: async (source, target) => {
+        await copyFile(source, target);
+      },
+      appendText: async (target, content) => {
+        await appendFile(target, content);
+      },
+      remove: async (target, options) => {
+        await rm(target, options);
+      },
+      inspect: async (target) => {
+        try {
+          const stats = await lstat(target);
+          return {
+            name: target,
+            isFile: stats.isFile(),
+            isDirectory: stats.isDirectory(),
+            isSymbolicLink: stats.isSymbolicLink()
+          };
+        } catch (error) {
+          if (error.code === "ENOENT") return null;
+          throw error;
+        }
+      },
+      list: async (target) => {
+        const entries = await readdir(target, { withFileTypes: true });
+        return Promise.all(
+          entries.sort((left, right) => left.name.localeCompare(right.name)).map(async (entry) => {
+            const stats = await lstat(path9.join(target, entry.name));
+            return {
+              name: entry.name,
+              isFile: stats.isFile(),
+              isDirectory: stats.isDirectory(),
+              isSymbolicLink: stats.isSymbolicLink()
+            };
+          })
+        );
+      }
+    },
+    operations: new OperationJournal(),
+    outputMode: "human",
+    ...overrides
+  };
 }
 
 // src/index.ts
 var HELP_TEXT = `create-next-pro
 
 Usage:
-  create-next-pro <project-name> [--force]
-  create-next-pro addpage [options]
-  create-next-pro addcomponent [options]
-  create-next-pro addlib [name]
-  create-next-pro addapi [name]
-  create-next-pro addlanguage [locale]
-  create-next-pro addtext <path> [text]
-  create-next-pro rmpage [options]
+  create-next-pro <project-name> [--force] [--json]
+  create-next-pro addpage [options] [--json]
+  create-next-pro addcomponent [options] [--json]
+  create-next-pro addlib [name] [--json]
+  create-next-pro addapi [name] [--json]
+  create-next-pro addlanguage [locale] [--json]
+  create-next-pro addtext <path> [text] [--json]
+  create-next-pro rmpage [options] [--json]
 
 Options:
   --help          Show this help message
   --version       Show the CLI version
+  --json          Emit one deterministic JSON document
   --reconfigure   Run the configuration assistant again
 `;
 function parseOptions(args) {
@@ -1550,51 +2568,114 @@ function parseOptions(args) {
     force: args.includes("--force"),
     help: args.includes("--help"),
     version: args.includes("--version") || args.includes("-v"),
-    reconfigure: args.includes("--reconfigure")
+    reconfigure: args.includes("--reconfigure"),
+    json: args.includes("--json")
   };
 }
+function withoutGlobalOptions(args) {
+  return args.filter((argument) => argument !== "--json");
+}
 async function packageVersion(context) {
   const packageJson = JSON.parse(
-    await context.fs.readText(path8.join(context.packageRoot, "package.json"))
+    await context.fs.readText(path10.join(context.packageRoot, "package.json"))
   );
   return packageJson.version;
 }
-async function main(context = createNodeContext()) {
-  try {
-    const args = [...context.argv];
-    const options = parseOptions(args);
-    const version = await packageVersion(context);
-    if (args[0] === "__complete") {
-      await printCompletions(args, context);
-      return 0;
-    }
-    if (options.help) {
-      context.terminal.log(HELP_TEXT);
-      return 0;
-    }
-    if (options.version) {
-      context.terminal.log(`v${version}`);
-      return 0;
+function interactiveInputError(message, hint) {
+  throw new CliError(message, {
+    code: "INTERACTIVE_INPUT_REQUIRED",
+    hint
+  });
+}
+async function executeCli(context) {
+  const options = parseOptions(context.argv);
+  context.outputMode = options.json ? "json" : "human";
+  const args = withoutGlobalOptions(context.argv);
+  const version = await packageVersion(context);
+  if (options.help) {
+    return commandResult(context, {
+      command: "help",
+      summary: "Displayed create-next-pro help.",
+      projectRoot: context.cwd,
+      status: "success",
+      data: { help: HELP_TEXT }
+    });
+  }
+  if (options.version) {
+    return commandResult(context, {
+      command: "version",
+      summary: `create-next-pro version ${version}.`,
+      projectRoot: context.cwd,
+      status: "success",
+      data: { version }
+    });
+  }
+  const config = await readConfig(context);
+  if (options.reconfigure) {
+    if (options.json) {
+      interactiveInputError(
+        "Reconfiguration is interactive and unavailable in JSON mode.",
+        "Run create-next-pro --reconfigure without --json."
+      );
     }
-    if (options.reconfigure || !await readConfig(context)) {
-      await onboarding(context, version);
-      return 0;
+    return onboarding(context, version);
+  }
+  if (!config) {
+    if (options.json) {
+      throw new CliError("Initial configuration is required.", {
+        code: "ONBOARDING_REQUIRED",
+        scope: "config",
+        path: "config.json",
+        hint: "Run create-next-pro once without --json, then rerun the command."
+      });
     }
-    if (args[0] === "addpage" && args.length === 1) args.push("-LPl");
-    const handler = args[0] ? createCommandRegistry().get(args[0]) : void 0;
-    if (handler) return (await handler(args, context)).exitCode;
-    const nameArg = args.find((arg) => !arg.startsWith("--"));
-    if (nameArg) {
-      await createProject(nameArg, options.force, context);
-      return 0;
+    return onboarding(context, version);
+  }
+  const command = args[0];
+  const handler = command ? createCommandRegistry().get(command) : void 0;
+  if (handler) return handler(args, context);
+  const nameArg = args.find(
+    (argument) => !argument.startsWith("--") && argument !== "-v"
+  );
+  if (nameArg) return createProject(nameArg, options.force, context);
+  if (options.json) {
+    interactiveInputError(
+      "A project name is required in JSON mode.",
+      "Pass the project name as a positional argument."
+    );
+  }
+  return createProjectWithPrompt(context);
+}
+async function runCompletion(context, args) {
+  try {
+    for (const candidate of await completionCandidates(args[1], context)) {
+      context.terminal.log(candidate);
     }
-    await createProjectWithPrompt(context);
     return 0;
+  } catch {
+    return 1;
+  }
+}
+async function main(context = createNodeContext()) {
+  const completionArgs = withoutGlobalOptions(context.argv);
+  if (completionArgs[0] === "__complete") {
+    return runCompletion(context, completionArgs);
+  }
+  context.operations.reset();
+  context.outputMode = parseOptions(context.argv).json ? "json" : "human";
+  let result;
+  try {
+    result = await executeCli(context);
   } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    context.terminal.error(message);
-    return error instanceof CliError ? error.exitCode : 1;
+    const command = completionArgs[0] ?? "create";
+    result = failedResult(context, command, error, {
+      projectRoot: context.cwd,
+      configRoot: configDirectory(context),
+      homeRoot: context.homeDir
+    });
   }
+  renderResult(result, context, context.outputMode);
+  return result.exitCode;
 }
 
 // bin.node.ts