create-next-pro-cli 0.1.26 → 0.1.28

package/dist/bin.node.js

@@ -1,30 +1,562 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import fs from "fs";
-import os from "os";
+import path10 from "path";
+
+// src/cli/completion.ts
+import path2 from "path";
+
+// src/core/page-catalog.ts
 import path from "path";
-import prompts8 from "prompts";
-import { fileURLToPath as fileURLToPath2 } from "url";
-import { dirname, resolve } from "path";
+function isRouteGroup(segment) {
+  return segment.startsWith("(") && segment.endsWith(")");
+}
+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 fs.list(directory);
+    } catch {
+      return;
+    }
+    if (entries.some((entry) => entry.isFile && entry.name === "page.tsx")) {
+      const routeSegments = relative.filter(
+        (segment) => !isRouteGroup(segment)
+      );
+      if (routeSegments.length > 0 && !routeSegments.some(
+        (segment) => segment.startsWith("_") || segment.startsWith("[")
+      )) {
+        const logicalName = routeSegments.join(".");
+        candidates.push({
+          logicalName,
+          routeSegments,
+          routeDirectory: directory,
+          uiDirectory: path.join(projectRoot, "src", "ui", ...routeSegments),
+          messageFile: path.join(
+            projectRoot,
+            "messages",
+            "{locale}",
+            `${routeSegments[0]}.json`
+          ),
+          messageKey: routeSegments.length > 1 ? routeSegments.at(-1) : void 0
+        });
+      }
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory && !entry.name.startsWith(".")) {
+        await visit(path.join(directory, entry.name), [
+          ...relative,
+          entry.name
+        ]);
+      }
+    }
+  }
+  await visit(appRoot);
+  return candidates.sort(
+    (left, right) => left.logicalName.localeCompare(right.logicalName)
+  );
+}
 
-// src/lib/addComponent.ts
+// src/cli/completion.ts
+var PUBLIC_COMMANDS = [
+  "addpage",
+  "addcomponent",
+  "addlib",
+  "addapi",
+  "addlanguage",
+  "addtext",
+  "rmpage",
+  "--help",
+  "--version",
+  "--json",
+  "--reconfigure"
+];
+var OPTIONS = {
+  addpage: [
+    "--layout",
+    "--page",
+    "--loading",
+    "--not-found",
+    "--error",
+    "--global-error",
+    "--route",
+    "--template",
+    "--default"
+  ],
+  addcomponent: ["--page", "-P"]
+};
+async function directories(root, context) {
+  try {
+    return (await context.fs.list(root)).filter((entry) => entry.isDirectory && !entry.name.startsWith("_")).map((entry) => entry.name).sort();
+  } catch {
+    return [];
+  }
+}
+async function completionCandidates(command, context) {
+  if (!command) return [...PUBLIC_COMMANDS];
+  if (command === "rmpage") {
+    return (await discoverPages(context.cwd, context.fs)).map(
+      (candidate) => candidate.logicalName
+    );
+  }
+  if (command === "addcomponent" || command === "addpage") {
+    return [
+      ...OPTIONS[command] ?? [],
+      ...await directories(path2.join(context.cwd, "src", "ui"), context)
+    ];
+  }
+  if (command === "addlanguage")
+    return ["de", "en", "es", "fr", "it", "ja", "pt"];
+  return OPTIONS[command] ?? [];
+}
+
+// src/cli/onboarding.ts
+import path4 from "path";
+
+// src/core/operations.ts
+import path3 from "path";
+
+// src/core/contracts.ts
+var CliError = class extends Error {
+  exitCode;
+  code;
+  hint;
+  scope;
+  path;
+  constructor(message, options = {}) {
+    super(message);
+    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
+    });
+  }
+};
+
+// 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, readFile as readFile2, writeFile, readdir } from "fs/promises";
-import prompts from "prompts";
 
 // 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);
 }
-async function loadConfig() {
-  const configPath = join(process.cwd(), "cnp.config.json");
-  if (!existsSync(configPath)) return null;
+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(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;
@@ -55,598 +587,1750 @@ function toFileName(key) {
   }
 }
 
+// src/core/project-paths.ts
+import path6 from "path";
+var SAFE_SEGMENT = /^[A-Za-z][A-Za-z0-9_-]*$/;
+function hasControlCharacters(value) {
+  return [...value].some((character) => {
+    const code = character.charCodeAt(0);
+    return code <= 31 || code === 127;
+  });
+}
+function parseLogicalName(value, label = "name") {
+  if (!value || hasControlCharacters(value)) {
+    throw new CliError(
+      `Invalid ${label}: a non-empty printable value is required.`,
+      { code: "INVALID_ARGUMENT" }
+    );
+  }
+  if (path6.isAbsolute(value) || value.includes("/") || value.includes("\\")) {
+    throw new CliError(
+      `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.`,
+      { code: "INVALID_ARGUMENT" }
+    );
+  }
+  return segments;
+}
+function validateProjectName(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.",
+      { code: "INVALID_ARGUMENT" }
+    );
+  }
+  return value;
+}
+function resolveInside(root, ...segments) {
+  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}`,
+      { code: "UNSAFE_PATH" }
+    );
+  }
+  return target;
+}
+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 = 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;
+}
+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/*").',
+      { code: "INVALID_ARGUMENT" }
+    );
+  }
+  return value;
+}
+
+// src/lib/addApi.ts
+var addApi = async (args, context) => {
+  let apiName = args[1];
+  if (!apiName || apiName.startsWith("-")) {
+    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: "API route name to add:",
+      validate: (name) => name ? true : "API route name is required"
+    });
+    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(context);
+  if (!config) {
+    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 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 (!context.fs.exists(routeTemplate)) {
+    throw new CliError("API template route.ts was not found.", {
+      code: "TEMPLATE_MISSING",
+      scope: "package",
+      path: "templates/Api/route.ts"
+    });
+  }
+  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 { existsSync as existsSync2, statSync } from "fs";
-async function addComponent(args) {
+import { join as join3 } from "path";
+var addComponent = async (args, context) => {
   let componentName = args[1];
-  let pageScope = null;
-  let 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 = join2(...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 prompts.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 config = await loadConfig();
+  const componentSegments = parseLogicalName(componentName, "component name");
+  if (componentSegments.length !== 1) {
+    throw new CliError("Component names must contain exactly one segment.", {
+      code: "INVALID_ARGUMENT"
+    });
+  }
+  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 = join2(
-    new URL("..", import.meta.url).pathname,
-    "templates",
-    "Component"
-  );
-  let messagesPath = null;
-  if (useI18n) {
-    messagesPath = join2(process.cwd(), "messages");
-    if (!existsSync2(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"
+    });
+  }
+  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"
+      });
+    }
+    const templateMessages = JSON.parse(
+      await context.fs.readText(messagesTemplate)
+    );
+    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 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`
+            }
+          );
+        }
+      }
+      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];
+      }
+      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)}
+`
+      });
     }
   }
-  let componentTargetPath;
-  let translationKey;
-  if (pageScope) {
-    if (nestedPath) {
-      componentTargetPath = join2(process.cwd(), "src", "ui", nestedPath);
-      translationKey = pageScope;
+  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 {
-      componentTargetPath = join2(process.cwd(), "src", "ui", pageScope);
-      translationKey = pageScope;
+      await gateway.write(item.target, item.content, {
+        role: "translation-messages",
+        detail: {
+          locale: item.locale,
+          key: `${translationNamespace}.${componentNameUpper}`
+        }
+      });
     }
-  } else {
-    componentTargetPath = join2(process.cwd(), "src", "ui", "_global");
-    translationKey = "_global_ui";
-  }
-  if (!existsSync2(componentTargetPath)) {
-    await mkdir(componentTargetPath, { recursive: true });
-  }
-  const componentFile = join2(componentTargetPath, `${componentNameUpper}.tsx`);
-  const templateComponentPath = join2(templatePath, "Component.tsx");
-  if (existsSync2(templateComponentPath)) {
-    let content = await readFile2(templateComponentPath, "utf-8");
-    content = content.replace(/Component/g, componentNameUpper).replace(/componentPage/g, translationKey);
-    await writeFile(componentFile, content);
-    console.log(`\u{1F4C4} File created: ${componentFile}`);
-  } else {
-    console.error(
-      "\u274C Template Component.tsx introuvable :",
-      templateComponentPath
-    );
   }
-  if (useI18n && messagesPath) {
-    const entries = await readdir(messagesPath, { withFileTypes: true });
-    const langDirs = entries.filter((e) => e.isDirectory()).map((e) => e.name);
-    const jsonTemplate = join2(templatePath, "component.json");
-    if (!existsSync2(jsonTemplate)) {
-      console.error("\u274C Template component.json not found:", jsonTemplate);
-      return;
+  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";
+function generateLocales() {
+  const names = new Intl.DisplayNames(["en"], { type: "language" });
+  const locales = [];
+  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 = names.of(code);
+        if (name && name.toLowerCase() !== code) locales.push(code);
+      } catch {
+      }
     }
-    const jsonContent = await readFile2(jsonTemplate, "utf-8");
-    const parsed = JSON.parse(jsonContent);
-    for (const locale of langDirs) {
-      const localeDir = join2(messagesPath, locale);
-      if (!existsSync2(localeDir) || !statSync(localeDir).isDirectory())
-        continue;
-      let jsonTarget;
-      if (pageScope) {
-        jsonTarget = join2(messagesPath, locale, `${pageScope}.json`);
-      } else {
-        jsonTarget = join2(messagesPath, locale, `_global_ui.json`);
+  }
+  return locales.sort();
+}
+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) {
+    throw new CliError("Internationalization is not enabled in this project.", {
+      code: "I18N_DISABLED"
+    });
+  }
+  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) {
+    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: "Locale to add:",
+      choices: available.map((value) => ({ title: value, value }))
+    });
+    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"
+      });
+    }
+  }
+  parseLogicalName(locale, "locale");
+  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(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"
+      }
+    );
+  }
+  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 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}`
       }
-      let current = {};
-      if (existsSync2(jsonTarget)) {
-        const jsonFile = await readFile2(jsonTarget, "utf-8");
-        current = JSON.parse(jsonFile);
+    );
+  }
+  if (!context.fs.exists(sourceAggregator)) {
+    throw new CliError("Default locale aggregator not found.", {
+      code: "CONFIG_NOT_FOUND",
+      scope: "project",
+      path: `messages/${defaultLocale}.ts`
+    });
+  }
+  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 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`
       }
-      current[componentNameUpper] = parsed;
-      await writeFile(jsonTarget, JSON.stringify(current, null, 2));
-      console.log(`\u{1F4C4} File updated: ${jsonTarget}`);
+    );
+  }
+  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;/
+  );
+  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 }
+      });
     }
-  } else {
-    console.log("\u2139\uFE0F Skipping translation entries; next-intl not enabled.");
+    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
+    });
   }
-  console.log(
-    `\u2705 Component "${componentNameUpper}" added ${pageScope ? `to page ${pageScope}` : "globally"}${useI18n ? " with localized messages" : ""}.`
+  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 nextRouting = routing.replace(
+    /locales:\s*\[[^\]]*\]/,
+    `locales: [${[...routingLocales, locale].map((value) => `"${value}"`).join(", ")}]`
+  );
+  const declarationIndex = registry.indexOf("const messages =");
+  const nextRegistry = registry.slice(0, declarationIndex) + `import ${locale} from "../../../messages/${locale}";
 
-// src/lib/addPage.ts
-import { join as join3 } from "path";
-import { mkdir as mkdir2, readFile as readFile3, writeFile as writeFile2, readdir as readdir2 } from "fs/promises";
-import prompts2 from "prompts";
-import { existsSync as existsSync3, statSync as statSync2 } from "fs";
-async function addPage(args) {
-  let pageName = args[1];
-  if (!pageName || pageName.startsWith("-")) {
-    const response = await prompts2.prompt({
-      type: "text",
-      name: "pageName",
-      message: "\u{1F4DD} Page name to add:",
-      validate: (name) => name ? true : "Page name is required"
+` + 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 }
     });
-    pageName = response.pageName;
-  }
-  let parentName = null;
-  let childName = null;
-  if (pageName.includes(".")) {
-    [parentName, childName] = pageName.split(".");
-  }
-  let shortFlags = args.find((arg) => /^-[A-Za-z]+$/.test(arg));
-  let 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;
+  }
+  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";
+var addLib = async (args, context) => {
+  let libArg = args[1];
+  if (!libArg || libArg.startsWith("-")) {
+    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: "Library name to add:",
+      validate: (name) => name ? true : "Library name is required"
+    });
+    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"
+      });
     }
   }
-  for (const flag of [
-    "layout",
-    "page",
-    "loading",
-    "not-found",
-    "error",
-    "global-error",
-    "route",
-    "template",
-    "default"
-  ]) {
-    if (longFlags.has("--" + flag)) flags.add(flag);
-  }
-  const config = await loadConfig();
-  if (!config) {
-    console.error(
-      "\u274C Configuration file cnp.config.json not found. Run this command from the project root."
+  const segments = parseLogicalName(libArg, "library name");
+  if (segments.length > 2) {
+    throw new CliError("Libraries support exactly library or library.module.", {
+      code: "INVALID_ARGUMENT"
+    });
+  }
+  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 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 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 (!context.fs.exists(indexPath)) {
+    await gateway.write(indexPath, await context.fs.readText(indexTemplate), {
+      role: "library-index"
+    });
+  }
+  let moduleAction;
+  if (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*${moduleIdentifier}\\s*}\\s*from\\s*["']\\./${fileName}["'];`
     );
-    return;
+    const exportRegex = /export\s*{([^}]*)}/m;
+    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(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" });
+  }
+  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`))
+        }
+      ]
+    });
   }
-  const useI18n = !!config.useI18n;
-  const srcSegments = ["src", "app"];
-  if (useI18n) srcSegments.push("[locale]");
-  const srcPath = join3(process.cwd(), ...srcSegments);
-  if (!existsSync3(srcPath)) {
-    console.error(`\u274C Expected directory not found: ${srcPath}`);
-    return;
+  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"]
+    });
   }
-  let messagesPath = null;
-  let locales = [];
-  if (useI18n) {
-    messagesPath = join3(process.cwd(), "messages");
-    if (!existsSync3(messagesPath)) {
-      console.error(
-        "\u274C Messages directory missing. Ensure i18n was configured."
-      );
-      return;
+  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";
+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 < 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 identifier = toIdentifier(fileName);
+  const importStatement = `import ${identifier} from "${importPath}";
+`;
+  const nextRegistry = registryMatch[0].replace(
+    /\n\};$/,
+    `
+  ${identifier},
+};`
+  );
+  return content.slice(0, declarationIndex) + importStatement + content.slice(declarationIndex).replace(registryMatch[0], nextRegistry);
+}
+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: "Page name to add:",
+      validate: (name) => name ? true : "Page name is required"
+    });
+    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"
+      });
     }
-    const entries = await readdir2(messagesPath, { withFileTypes: true });
-    locales = entries.filter((e) => e.isDirectory()).map((e) => e.name);
   }
-  const templatePath = join3(
-    new URL("..", import.meta.url).pathname,
-    "templates",
-    "Page"
+  const pageSegments = parseLogicalName(logicalName, "page name");
+  if (pageSegments.length > 2) {
+    throw new CliError("Nested pages support exactly Parent.Child.", {
+      code: "INVALID_ARGUMENT"
+    });
+  }
+  const flags = selectedFlags(args);
+  const config = await loadConfig(context);
+  if (!config) {
+    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 = Boolean(config.useI18n);
+  const aliasPrefix = configuredAliasPrefix(config);
+  const appRoot = join6(
+    context.cwd,
+    "src",
+    "app",
+    ...useI18n ? ["[locale]"] : []
   );
-  let uiPageDir, localePagePath, jsonFileName;
-  if (parentName && childName) {
-    uiPageDir = join3(process.cwd(), "src", "ui", parentName, childName);
-    localePagePath = join3(srcPath, parentName, childName);
-    jsonFileName = parentName;
-  } else {
-    uiPageDir = join3(process.cwd(), "src", "ui", pageName);
-    localePagePath = join3(srcPath, pageName);
-    jsonFileName = pageName;
-  }
-  if (!existsSync3(uiPageDir)) {
-    await mkdir2(uiPageDir, { recursive: true });
-  }
-  const uiPageFile = join3(uiPageDir, "page-ui.tsx");
-  const uiPageTemplate = join3(templatePath, "page-ui.tsx");
-  if (existsSync3(uiPageTemplate)) {
-    let uiContent = await readFile3(uiPageTemplate, "utf-8");
-    uiContent = uiContent.replace(/template/g, childName || pageName).replace(/Template/g, capitalize(childName || pageName));
-    await writeFile2(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 (!existsSync3(localePagePath)) {
-    await mkdir2(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 = join3(templatePath, filename);
-    const dst = join3(localePagePath, filename);
-    if (!existsSync3(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 readFile3(src, "utf-8");
-    const replaced = content.replace(/template/g, childName || pageName).replace(/Template/g, capitalize(childName || pageName));
-    await writeFile2(dst, replaced);
-    console.log(`\u{1F4C4} File created: ${dst}`);
-  }
-  if (useI18n && messagesPath) {
-    const jsonTemplate = join3(templatePath, "page.json");
-    if (!existsSync3(jsonTemplate)) {
-      console.warn("\u26A0\uFE0F Missing template: page.json at path:", jsonTemplate);
-    } else {
-      const content = await readFile3(jsonTemplate, "utf-8");
-      const replaced = content.replace(/template/g, childName || pageName).replace(/Template/g, capitalize(childName || pageName));
-      for (const locale of locales) {
-        const localeDir = join3(messagesPath, locale);
-        if (!existsSync3(localeDir) || !statSync2(localeDir).isDirectory())
-          continue;
-        const jsonTarget = join3(messagesPath, locale, `${jsonFileName}.json`);
-        let current = {};
-        if (existsSync3(jsonTarget)) {
-          const jsonFile = await readFile3(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 writeFile2(jsonTarget, JSON.stringify(current, null, 2));
-        console.log(`\u{1F4C4} File created: ${jsonTarget}`);
       }
+      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
+        )
+      });
+    }
+  }
+  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/rmPage.ts
-import { join as join4 } from "path";
-import { writeFile as writeFile3, readdir as readdir3 } from "fs/promises";
-import prompts3 from "prompts";
-import { existsSync as existsSync4 } from "fs";
-async function rmPage(args) {
-  let pageName = args[1];
-  if (!pageName || pageName.startsWith("-")) {
-    const response = await prompts3.prompt({
-      type: "text",
-      name: "pageName",
-      message: "\u{1F5D1}\uFE0F Page name to remove:",
-      validate: (name) => name ? true : "Page name is required"
+// src/lib/addText.ts
+import { join as join7 } from "path";
+function defaultText(key) {
+  return key.replace(/_/g, " ").replace(/\b\w/g, (character) => character.toUpperCase());
+}
+var addText = async (args, context) => {
+  const pathArg = args[1];
+  if (!pathArg) {
+    throw new CliError("Translation dot path is required.", {
+      code: "INVALID_ARGUMENT",
+      hint: "Use addtext domain.key followed by an optional value."
     });
-    pageName = response.pageName;
-  }
-  const messagesPath = join4(process.cwd(), "messages");
-  const entries = await readdir3(messagesPath, { withFileTypes: true });
-  const langDirs = entries.filter((e) => e.isDirectory()).map((e) => e.name);
-  for (const locale of langDirs) {
-    const jsonTarget = join4(messagesPath, locale, `${pageName}.json`);
-    if (existsSync4(jsonTarget)) {
-      await writeFile3(jsonTarget, "");
-      await import("child_process").then(
-        (cp3) => cp3.execSync(`rm -f '${jsonTarget}'`)
-      );
-      console.log(`\u{1F5D1}\uFE0F Deleted: ${jsonTarget}`);
+  }
+  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(" ");
+  const finalKey = segments.at(-1);
+  const text = providedText || defaultText(finalKey);
+  const config = await loadConfig(context);
+  if (!config?.useI18n) {
+    throw new CliError("Internationalization is not enabled in this project.", {
+      code: "I18N_DISABLED"
+    });
+  }
+  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 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 [fileName, ...keySegments] = segments;
+  const prepared = [];
+  for (const locale of locales) {
+    const file = join7(messagesRoot, locale, `${fileName}.json`);
+    await assertSafeTarget(context.cwd, file, context.fs);
+    const existed = context.fs.exists(file);
+    let data = {};
+    if (existed) {
+      try {
+        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 (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;
+    prepared.push({
+      locale,
+      file,
+      data,
+      replaced: previous !== void 0 && previous !== text
+    });
   }
-  const uiPageDir = join4(process.cwd(), "src", "ui", pageName);
-  if (existsSync4(uiPageDir)) {
-    await import("child_process").then(
-      (cp3) => cp3.execSync(`rm -rf '${uiPageDir}'`)
-    );
-    console.log(`\u{1F5D1}\uFE0F Deleted: ${uiPageDir}`);
+  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 appLocaleDir = join4(process.cwd(), "src", "app", "[locale]", pageName);
-  if (existsSync4(appLocaleDir)) {
-    await import("child_process").then(
-      (cp3) => cp3.execSync(`rm -rf '${appLocaleDir}'`)
+  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 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`
+      }
     );
-    console.log(`\u{1F5D1}\uFE0F Deleted: ${appLocaleDir}`);
   }
-  console.log(`\u2705 Page "${pageName}" deleted.`);
+  if (!hasImport) return { content, changed: false };
+  return {
+    content: content.replace(importPattern, "").replace(propertyPattern, ""),
+    changed: true
+  };
 }
-
-// src/lib/addLib.ts
-import { join as join5 } from "path";
-import { mkdir as mkdir3, readFile as readFile4, writeFile as writeFile4 } from "fs/promises";
-import prompts4 from "prompts";
-import { existsSync as existsSync5 } from "fs";
-async function addLib(args) {
-  let libArg = args[1];
-  if (!libArg || libArg.startsWith("-")) {
-    const response = await prompts4.prompt({
-      type: "text",
-      name: "libArg",
-      message: "\u{1F4E6} Lib name to add:",
-      validate: (name) => name ? true : "Lib name is required"
-    });
-    libArg = response.libArg;
+var rmPage = async (args, context) => {
+  const candidates = await discoverPages(context.cwd, context.fs);
+  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 page name returned by completion after rmpage."
+      });
+    }
+    const selected = await context.prompt([
+      {
+        type: "autocomplete",
+        name: "page",
+        message: "Page to remove:",
+        choices: candidates.map((candidate2) => ({
+          title: candidate2.logicalName.replaceAll(".", " > "),
+          value: candidate2.logicalName
+        }))
+      },
+      {
+        type: (value) => value ? "confirm" : null,
+        name: "confirm",
+        message: "Confirm page deletion?",
+        initial: false
+      }
+    ]);
+    if (!selected.confirm) {
+      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 ?? "");
   }
-  let libName = libArg;
-  let fileName = null;
-  if (libArg.includes(".")) {
-    [libName, fileName] = libArg.split(".");
+  parseLogicalName(logicalName, "page name");
+  const candidate = candidates.find(
+    (entry) => entry.logicalName === logicalName
+  );
+  if (!candidate) {
+    throw new CliError(`Page not found: ${logicalName}.`, {
+      code: "TARGET_NOT_FOUND",
+      scope: "project",
+      path: logicalName.replaceAll(".", "/")
+    });
   }
-  const config = await loadConfig();
-  if (!config) {
-    console.error(
-      "\u274C Configuration file cnp.config.json not found. Run this command from the project root."
-    );
-    return;
+  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)}
+`
+      });
+    }
   }
-  const libDir = join5(process.cwd(), "src", "lib", libName);
-  if (!existsSync5(libDir)) {
-    await mkdir3(libDir, { recursive: true });
+  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 }
+      });
+    }
   }
-  const templateDir = join5(
-    new URL("..", import.meta.url).pathname,
-    "templates",
-    "Lib"
-  );
-  const indexTemplate = join5(templateDir, "index.ts");
-  const fileTemplate = join5(templateDir, "item.ts");
-  const indexPath = join5(libDir, "index.ts");
-  if (!existsSync5(indexPath)) {
-    if (existsSync5(indexTemplate)) {
-      const content = await readFile4(indexTemplate, "utf-8");
-      await writeFile4(indexPath, content);
+  for (const prepared of preparedAggregators) {
+    if (prepared.changed) {
+      await gateway.write(prepared.target, prepared.content, {
+        role: "locale-aggregator"
+      });
     } else {
-      await writeFile4(indexPath, "export {}\n");
+      gateway.unchanged(prepared.target, { role: "locale-aggregator" });
     }
-    console.log(`\u{1F4C4} File created: ${indexPath}`);
   }
-  if (fileName) {
-    const filePath = join5(libDir, `${fileName}.ts`);
-    if (!existsSync5(filePath)) {
-      if (existsSync5(fileTemplate)) {
-        let content = await readFile4(fileTemplate, "utf-8");
-        content = content.replace(/template/g, fileName).replace(/Template/g, capitalize(fileName));
-        await writeFile4(filePath, content);
-      } else {
-        await writeFile4(
-          filePath,
-          `export function ${fileName}() {
-  // TODO: implement
+  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 createCommandRegistry() {
+  return /* @__PURE__ */ new Map([
+    ["addcomponent", addComponent],
+    ["addpage", addPage],
+    ["addlib", addLib],
+    ["addapi", addApi],
+    ["addlanguage", addLanguage],
+    ["addtext", addText],
+    ["rmpage", rmPage]
+  ]);
 }
-`
+
+// src/scaffold.ts
+import { join as join8, resolve } from "path";
+import { fileURLToPath } from "url";
+
+// src/core/template-manifest.ts
+import path8 from "path";
+var TEMPLATE_DENY_NAMES = /* @__PURE__ */ new Set([
+  ".env",
+  ".git",
+  ".agent",
+  ".cursor",
+  ".next",
+  "node_modules",
+  "artifacts",
+  "coverage",
+  "playwright-report",
+  "test-results"
+]);
+function isDistributableTemplatePath(relativePath) {
+  const segments = relativePath.split(path8.sep);
+  return !segments.some(
+    (segment) => TEMPLATE_DENY_NAMES.has(segment) || segment.endsWith(".tsbuildinfo") || segment === ".DS_Store"
+  );
+}
+async function templateManifest(root, fs) {
+  const files = [];
+  async function visit(directory, relativeDirectory = "") {
+    const entries = await fs.list(directory);
+    for (const entry of entries) {
+      const relative = path8.join(relativeDirectory, entry.name);
+      if (!isDistributableTemplatePath(relative)) continue;
+      const source = path8.join(directory, entry.name);
+      if (entry.isSymbolicLink) {
+        throw new CliError(
+          `Symbolic links are forbidden in templates: ${relative}`,
+          { code: "UNSAFE_PATH", scope: "package", path: relative }
         );
       }
-      console.log(`\u{1F4C4} File created: ${filePath}`);
+      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
+        });
     }
-    let indexContent = await readFile4(indexPath, "utf-8");
-    const importLine = `import { ${fileName} } from "./${fileName}";`;
-    const importRegex = new RegExp(
-      `import\\s*{\\s*${fileName}\\s*}\\s*from\\s*"\\./${fileName}";`
+  }
+  await visit(root);
+  return files;
+}
+async function validateScaffoldTemplate(root, fs) {
+  const manifest = await templateManifest(root, fs);
+  for (const required of ["package.json", "tsconfig.json"]) {
+    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"))
     );
-    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 (!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"
       }
-    }
-    if (!imports.some((l) => importRegex.test(l))) {
-      imports.push(importLine);
-    }
-    if (!exportsSet.includes(fileName)) {
-      exportsSet.push(fileName);
-    }
-    indexContent = imports.join("\n") + "\n\nexport { " + exportsSet.join(", ") + " };\n";
-    await writeFile4(indexPath, indexContent);
-    console.log(`\u270F\uFE0F Updated index: ${indexPath}`);
+    );
   }
-  console.log(
-    `\u2705 Lib "${libName}"${fileName ? ` with module ${fileName}` : ""} added.`
-  );
+  return manifest;
 }
-
-// src/lib/addApi.ts
-import { join as join6 } from "path";
-import { mkdir as mkdir4, readFile as readFile5, writeFile as writeFile5 } from "fs/promises";
-import prompts5 from "prompts";
-import { existsSync as existsSync6 } from "fs";
-async function addApi(args) {
-  let apiName = args[1];
-  if (!apiName || apiName.startsWith("-")) {
-    const response = await prompts5.prompt({
-      type: "text",
-      name: "apiName",
-      message: "\u{1F50C} API route name to add:",
-      validate: (name) => name ? true : "API route name is required"
+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
+    );
+    const source = path8.join(root, relative);
+    await gateway.copy(source, destination, {
+      role: "template-file",
+      source: { template: `Projects/default/${relative}` }
     });
-    apiName = response.apiName;
   }
-  const config = await loadConfig();
-  if (!config) {
-    console.error(
-      "\u274C Configuration file cnp.config.json not found. Run this command from the project root."
+  return files;
+}
+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 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.',
+      {
+        code: "TEMPLATE_MISSING",
+        scope: "package",
+        path: "templates/Projects/default/tsconfig.json"
+      }
     );
-    return;
-  }
-  const apiDir = join6(process.cwd(), "src", "app", "api", apiName);
-  if (!existsSync6(apiDir)) {
-    await mkdir4(apiDir, { recursive: true });
   }
-  const templateDir = join6(
-    new URL("..", import.meta.url).pathname,
-    "templates",
-    "Api"
+  await gateway.write(
+    tsconfigPath,
+    tsconfigContent.replace('"@/*"', `"${importAlias}"`),
+    { role: "typescript-configuration" }
   );
-  const routeTemplate = join6(templateDir, "route.ts");
-  const routePath = join6(apiDir, "route.ts");
-  if (!existsSync6(routePath)) {
-    if (existsSync6(routeTemplate)) {
-      let content = await readFile5(routeTemplate, "utf-8");
-      content = content.replace(/template/g, apiName);
-      await writeFile5(routePath, content);
-    } else {
-      await writeFile5(
-        routePath,
-        `import { NextResponse } from "next/server";
-
-export async function GET() {
-  return NextResponse.json({ message: "Hello from ${apiName}" });
-}
-`
-      );
+  if (importAlias !== "@/*") {
+    const prefix = importAlias.slice(0, -2);
+    for (const relative of await templateManifest(target, context.fs)) {
+      if (!/\.[cm]?[jt]sx?$/.test(relative)) continue;
+      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 gateway.write(file, next, { role: "import-alias-reference" });
+      }
     }
-    console.log(`\u{1F4C4} File created: ${routePath}`);
-  } else {
-    console.log(`\u2139\uFE0F File already exists: ${routePath}`);
   }
-  console.log(`\u2705 API route "${apiName}" added.`);
-}
-
-// src/scaffold.ts
-import { cp, mkdir as mkdir5, rm, writeFile as writeFile6, readFile as readFile6 } from "fs/promises";
-import { join as join7 } from "path";
-import { existsSync as existsSync7 } from "fs";
-import { fileURLToPath } 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;
 }
 
 // src/scaffold.ts
-async function scaffoldProject(options) {
-  const targetPath = join7(process.cwd(), options.projectName);
-  const __dirname2 = new URL(".", import.meta.url);
-  const templatePath = join7(
-    fileURLToPath(__dirname2),
-    "..",
-    "templates",
-    "Projects",
-    "default"
+async function scaffoldProject(options, runtime) {
+  const requiredFeatures = [
+    "useTypescript",
+    "useEslint",
+    "useTailwind",
+    "useSrcDir",
+    "useTurbopack",
+    "useI18n"
+  ];
+  const unsupported = requiredFeatures.filter(
+    (feature) => options[feature] !== true
+  );
+  if (unsupported.length > 0) {
+    throw new CliError(
+      `The default Next.js 16 template requires: ${unsupported.join(", ")}.`,
+      { code: "INVALID_ARGUMENT" }
+    );
+  }
+  const { context } = runtime;
+  const cwd = context.cwd;
+  const projectName = validateProjectName(options.projectName);
+  const importAlias = normalizeImportAlias(
+    options.customAlias === false ? "@/*" : options.importAlias || "@/*"
   );
-  if (existsSync7(targetPath)) {
+  const targetPath = join8(cwd, projectName);
+  const __dirname = new URL(".", import.meta.url);
+  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.",
+      { code: "UNSAFE_PATH" }
+    );
+  }
+  const gateway = new MutationGateway(context, targetPath);
+  const manifest = await validateScaffoldTemplate(templatePath, context.fs);
+  if (context.fs.exists(targetPath)) {
     if (options.force) {
-      console.warn("\u26A0\uFE0F Target directory already exists, removing...");
-      await rm(targetPath, { recursive: true, force: true });
+      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 {
-      console.error(
-        red("[X] Target directory already exists. Use --force to overwrite.")
+      throw new CliError(
+        "Target directory already exists. Use --force to overwrite it.",
+        {
+          code: "TARGET_EXISTS",
+          scope: "project",
+          path: "."
+        }
       );
-      process.exit(1);
     }
   }
-  try {
-    console.log("Creating project directory...");
-    await mkdir5(targetPath, { recursive: true });
-    console.log("Copying files from template...");
-    await cp(templatePath, targetPath, { recursive: true });
-    const pkgPath = join7(targetPath, "package.json");
-    if (existsSync7(pkgPath)) {
-      const pkg = JSON.parse(await readFile6(pkgPath, "utf-8"));
-      pkg.dependencies = pkg.dependencies || {};
-      if (options.useI18n) {
-        pkg.dependencies["next-intl"] = pkg.dependencies["next-intl"] || "^4.3.5";
-      }
-      await writeFile6(pkgPath, JSON.stringify(pkg, null, 2));
+  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" }
     }
-    await writeFile6(
-      join7(targetPath, "cnp.config.json"),
-      JSON.stringify(options, null, 2)
-    );
-    console.log("Project setup complete!");
-    console.log("");
-    console.log("To get started:");
-    console.log("    " + green(`cd ${options.projectName}`));
-    console.log("");
-    console.log(
-      "Then install dependencies and launch the dev server with your preferred tool:"
-    );
-    console.log("    " + green(`bun install && bun dev`));
-    console.log("    " + green(`npm install && npm run dev`));
-    console.log("    " + green(`pnpm install && pnpm run dev`));
-    console.log("");
-    console.log("Documentation and examples can be found at:");
-    console.log(
-      "    " + cyan("https://github.com/Rising-Corporation/create-next-pro-cli")
-    );
-    console.log(
-      "_-`'-_-'`_`'-_-'`_`'-_-'`_`'-_-'`_`'-_-'`_`'-_-'`_`'-_-'`_`'-_-'`-_"
-    );
-  } catch (err) {
-    console.error(red("[X] Error during project creation:"), err);
-    process.exit(1);
-  }
+  );
+  return { projectRoot: targetPath, copiedFiles: manifest.length, importAlias };
 }
 
 // src/lib/createProject.ts
-async function createProject(nameArg, force) {
+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,
     useTypescript: true,
@@ -659,14 +2343,12 @@ async function createProject(nameArg, force) {
     importAlias: "@/*",
     force
   };
-  console.log(`Creating project "${response.projectName}"...`);
-  await scaffoldProject(response);
+  return createProjectFromOptions(response, context);
 }
 
 // src/lib/createProjectWithPrompt.ts
-import prompts6 from "prompts";
-async function createProjectWithPrompt() {
-  const response = await prompts6.prompt([
+async function createProjectWithPrompt(context) {
+  const response = await context.prompt([
     {
       type: "text",
       name: "projectName",
@@ -736,314 +2418,252 @@ async function createProjectWithPrompt() {
       initial: "@core/*"
     }
   ]);
-  console.log("\nYour choices:");
-  console.log(response);
-  await scaffoldProject(response);
-}
-
-// src/lib/addLanguage.ts
-import { join as join8 } from "path";
-import { existsSync as existsSync8 } from "fs";
-import { cp as cp2, readFile as readFile7, writeFile as writeFile7 } from "fs/promises";
-import prompts7 from "prompts";
-function generateLocales() {
-  const dn = 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);
-      try {
-        const name = dn.of(code);
-        if (name && name.toLowerCase() !== code) {
-          locales.push(code);
-        }
-      } catch {
-      }
-    }
-  }
-  return locales.sort();
-}
-async function addLanguage(args) {
-  const config = await loadConfig();
-  if (!config?.useI18n) {
-    console.error("\u274C i18n is not enabled in this project.");
-    return;
-  }
-  const messagesPath = join8(process.cwd(), "messages");
-  if (!existsSync8(messagesPath)) {
-    console.error("\u274C Messages directory missing. Ensure i18n was configured.");
-    return;
-  }
-  const available = generateLocales();
-  let locale = args[1];
-  if (!locale || !available.includes(locale)) {
-    const response = await prompts7({
-      type: "autocomplete",
-      name: "locale",
-      message: "\u{1F310} Locale to add:",
-      choices: available.map((l) => ({ title: l, value: l }))
+  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"
     });
-    locale = response.locale;
-  }
-  if (!locale) return;
-  if (existsSync8(join8(messagesPath, locale))) {
-    console.error(`\u274C Locale ${locale} already exists.`);
-    return;
-  }
-  const routingFile = join8(process.cwd(), "src", "lib", "i18n", "routing.ts");
-  if (!existsSync8(routingFile)) {
-    console.error("\u274C routing.ts not found. Are you in project root?");
-    return;
-  }
-  const routingContent = await readFile7(routingFile, "utf-8");
-  const defaultMatch = routingContent.match(/defaultLocale:\s*"([^"]+)"/);
-  const defaultLocale = defaultMatch ? defaultMatch[1] : null;
-  if (!defaultLocale || !existsSync8(join8(messagesPath, defaultLocale))) {
-    console.error("\u274C Default locale not found.");
-    return;
-  }
-  await cp2(join8(messagesPath, defaultLocale), join8(messagesPath, locale), {
-    recursive: true
-  });
-  console.log(`\u{1F4C4} Directory created: ${join8(messagesPath, locale)}`);
-  const localesMatch = routingContent.match(/locales:\s*\[([^\]]*)\]/);
-  if (localesMatch) {
-    const localesArr = localesMatch[1].split(",").map((s) => s.trim().replace(/["']/g, "")).filter(Boolean);
-    if (!localesArr.includes(locale)) {
-      localesArr.push(locale);
-      const newLocales = `locales: [${localesArr.map((l) => `"${l}"`).join(", ")}]`;
-      const newContent = routingContent.replace(/locales:\s*\[[^\]]*\]/, newLocales);
-      await writeFile7(routingFile, newContent);
-      console.log(`\u{1F4C4} File updated: ${routingFile}`);
-    }
   }
-  console.log(
-    `\u2705 Locale "${locale}" added and copied from default locale "${defaultLocale}".`
-  );
+  const options = response;
+  return createProjectFromOptions(options, context);
 }
 
-// src/lib/addText.ts
-import { join as join9 } from "path";
-import { existsSync as existsSync9 } from "fs";
-import { readFile as readFile8, writeFile as writeFile8, readdir as readdir4 } from "fs/promises";
-function defaultText(key) {
-  return key.replace(/_/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
-}
-async function addText(args) {
-  const pathArg = args[1];
-  if (!pathArg) {
-    console.error("\u274C Dot path parameter is required.");
-    return;
-  }
-  const providedText = args.slice(2).join(" ");
-  const config = await loadConfig();
-  if (!config?.useI18n) {
-    console.error("\u274C i18n is not enabled in this project.");
-    return;
-  }
-  const messagesPath = join9(process.cwd(), "messages");
-  if (!existsSync9(messagesPath)) {
-    console.error("\u274C Messages directory missing. Ensure i18n was configured.");
-    return;
-  }
-  const entries = await readdir4(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 finalKey = segments[segments.length - 1];
-  const text = providedText || defaultText(finalKey);
-  for (const locale of locales) {
-    const filePath = join9(messagesPath, locale, `${fileName}.json`);
-    let data = {};
-    if (existsSync9(filePath)) {
-      const raw = await readFile8(filePath, "utf-8");
-      try {
-        data = JSON.parse(raw);
-      } catch {
-      }
-    }
-    let cursor = data;
-    for (let i = 0; i < segments.length - 1; i++) {
-      const seg = segments[i];
-      if (!cursor[seg]) cursor[seg] = {};
-      cursor = cursor[seg];
+// 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}`);
     }
-    cursor[finalKey] = text;
-    await writeFile8(filePath, JSON.stringify(data, null, 2));
-    console.log(`\u{1F4C4} File updated: ${filePath}`);
-  }
-  console.log(`\u2705 Text added at path "${pathArg}" with value "${text}".`);
-}
-
-// src/index.ts
-var CONFIG_DIR = process.env.XDG_CONFIG_HOME ? path.join(process.env.XDG_CONFIG_HOME, "create-next-pro") : path.join(os.homedir(), ".config", "create-next-pro");
-var CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
-function readCfg() {
-  try {
-    return JSON.parse(fs.readFileSync(CONFIG_FILE, "utf8"));
-  } catch {
-    return null;
+    current = parent;
   }
 }
-function writeCfg(cfg) {
-  fs.mkdirSync(CONFIG_DIR, { recursive: true });
-  fs.writeFileSync(CONFIG_FILE, JSON.stringify(cfg, null, 2));
-}
-function rcFile(shell) {
-  return path.join(os.homedir(), shell === "zsh" ? ".zshrc" : ".bashrc");
-}
-function ensureLineInRc(file, line) {
-  try {
-    const cur = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
-    if (!cur.includes(line)) fs.appendFileSync(file, `
-${line}
-`);
-  } catch {
-  }
-}
-async function installCompletion(shell) {
-  const __dirname2 = path.dirname(fileURLToPath2(import.meta.url));
-  const completionSrc = path.resolve(
-    __dirname2,
-    "../create-next-pro-completion.sh"
-  );
-  const completionDst = path.join(CONFIG_DIR, "completion.sh");
-  fs.mkdirSync(CONFIG_DIR, { recursive: true });
-  fs.copyFileSync(completionSrc, completionDst);
-  ensureLineInRc(rcFile(shell), `source "${completionDst}"`);
+function resolvePackageRoot(metaUrl = import.meta.url) {
+  return findPackageRoot(path9.dirname(fileURLToPath2(metaUrl)));
 }
-var __filename = fileURLToPath2(import.meta.url);
-var __dirname = dirname(__filename);
-var packageJsonPath = resolve(__dirname, "../package.json");
-var packageJson = fs.readFileSync(packageJsonPath, "utf8");
-async function onboarding() {
-  const pkg = JSON.parse(packageJson);
-  console.log(`\u{1F680} Welcome to create-next-pro v${pkg.version}
-`);
-  const res = await prompts8(
-    [
-      {
-        type: "select",
-        name: "shell",
-        message: "Which shell do you use?",
-        choices: [
-          { title: "zsh", value: "zsh" },
-          { title: "bash", value: "bash" }
-        ],
-        initial: (os.userInfo().shell || "").includes("zsh") ? 0 : 1
+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);
       },
-      {
-        type: "toggle",
-        name: "completion",
-        message: "Install autocompletion?",
-        initial: true,
-        active: "Yes",
-        inactive: "No"
+      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()
+            };
+          })
+        );
       }
-    ],
-    { onCancel: () => process.exit(1) }
-  );
-  const cfg = {
-    version: 1,
-    shell: res.shell,
-    completionInstalled: !!res.completion,
-    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-    updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    },
+    operations: new OperationJournal(),
+    outputMode: "human",
+    ...overrides
   };
-  if (cfg.completionInstalled) await installCompletion(cfg.shell);
-  writeCfg(cfg);
-  console.log("\n\u2705 Configuration saved.");
-  console.log("you can now use the CLI ! ex : ");
-  console.log("  Without prompt (will change in future) :");
-  console.log("    create-next-pro my-next-project");
-  console.log("  With prompt :");
-  console.log("    create-next-pro");
-  console.log(
-    "For more information, visit: https://github.com/Rising-Corporation/create-next-pro-cli"
-  );
-  console.log("Happy coding!  \u{1F389}");
-  return cfg;
 }
-function showHelp() {
-  console.log(`create-next-pro
+
+// 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) {
+  return {
+    force: args.includes("--force"),
+    help: args.includes("--help"),
+    version: args.includes("--version") || args.includes("-v"),
+    reconfigure: args.includes("--reconfigure"),
+    json: args.includes("--json")
+  };
 }
-function showVersion() {
-  const pkg = JSON.parse(packageJson);
-  console.log(`v${pkg.version}`);
+function withoutGlobalOptions(args) {
+  return args.filter((argument) => argument !== "--json");
 }
-async function main() {
-  let args;
-  if (typeof Bun !== "undefined") {
-    args = Bun.argv.slice(2);
-  } else if (typeof process !== "undefined" && process.argv) {
-    args = process.argv.slice(2);
-  } else {
-    args = [];
-  }
-  if (args.includes("--help")) return showHelp();
-  if (args.includes("--version") || args.includes("-v")) return showVersion();
-  if (args.includes("--reconfigure") || !readCfg()) {
-    await onboarding();
-    return;
-  }
-  const force = args.includes("--force");
-  if (args[0] === "addpage" && args.length === 1) {
-    args.push("-LPl");
-  }
-  if (args[0] === "addcomponent") {
-    addComponent(args);
-    return;
-  }
-  if (args[0] === "addpage") {
-    addPage(args);
-    return;
+async function packageVersion(context) {
+  const packageJson = JSON.parse(
+    await context.fs.readText(path10.join(context.packageRoot, "package.json"))
+  );
+  return packageJson.version;
+}
+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 (args[0] === "addlib") {
-    addLib(args);
-    return;
+  if (options.version) {
+    return commandResult(context, {
+      command: "version",
+      summary: `create-next-pro version ${version}.`,
+      projectRoot: context.cwd,
+      status: "success",
+      data: { version }
+    });
   }
-  if (args[0] === "addapi") {
-    addApi(args);
-    return;
+  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."
+      );
+    }
+    return onboarding(context, version);
   }
-  if (args[0] === "addlanguage") {
-    await addLanguage(args);
-    return;
+  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."
+      });
+    }
+    return onboarding(context, version);
   }
-  if (args[0] === "addtext") {
-    await addText(args);
-    return;
+  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."
+    );
   }
-  if (args[0] === "rmpage") {
-    rmPage(args);
-    return;
+  return createProjectWithPrompt(context);
+}
+async function runCompletion(context, args) {
+  try {
+    for (const candidate of await completionCandidates(args[1], context)) {
+      context.terminal.log(candidate);
+    }
+    return 0;
+  } catch {
+    return 1;
   }
-  const nameArg = args.find((arg) => !arg.startsWith("--"));
-  if (nameArg) {
-    createProject(nameArg, force);
-    return;
+}
+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 command = completionArgs[0] ?? "create";
+    result = failedResult(context, command, error, {
+      projectRoot: context.cwd,
+      configRoot: configDirectory(context),
+      homeRoot: context.homeDir
+    });
   }
-  await createProjectWithPrompt();
+  renderResult(result, context, context.outputMode);
+  return result.exitCode;
 }
 
 // bin.node.ts
-main();
+process.exitCode = await main();
 //# sourceMappingURL=bin.node.js.map