@nage-api/cli 1.0.0-beta.2

package/dist/workspace/manifest.js

@@ -0,0 +1,162 @@
+"use strict";
+/**
+ * `nage.workspace.json` — the source of truth for the workspace (PLAN.md §10.4).
+ *
+ * Successor to the legacy single-file `.nac-metadata.json`, extended for many
+ * apps. `new app` / `remove app` / `add` / `list` / `doctor` all read and write
+ * it, and it is serialised deterministically so a regenerated manifest produces
+ * an empty diff rather than reordered noise.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_PORT = exports.MANIFEST_FILE = void 0;
+exports.createManifest = createManifest;
+exports.serialiseManifest = serialiseManifest;
+exports.parseManifest = parseManifest;
+exports.findWorkspaceRoot = findWorkspaceRoot;
+exports.loadWorkspace = loadWorkspace;
+exports.resolveTargetApp = resolveTargetApp;
+exports.nextAvailablePort = nextAvailablePort;
+const promises_1 = require("node:fs/promises");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const core_1 = require("@nage-api/core");
+exports.MANIFEST_FILE = 'nage.workspace.json';
+exports.DEFAULT_PORT = 3000;
+function createManifest(input) {
+    return {
+        version: 1,
+        name: input.name,
+        engine: input.engine,
+        frameworkVersion: input.frameworkVersion,
+        apps: [],
+        packages: [],
+    };
+}
+/** Serialise deterministically: sorted collections, stable key order, trailing newline. */
+function serialiseManifest(manifest) {
+    const ordered = {
+        version: manifest.version,
+        name: manifest.name,
+        engine: manifest.engine,
+        frameworkVersion: manifest.frameworkVersion,
+        apps: [...manifest.apps]
+            .sort((left, right) => left.name.localeCompare(right.name))
+            .map((app) => ({
+            name: app.name,
+            preset: app.preset,
+            port: app.port,
+            features: [...app.features].sort(),
+        })),
+        packages: [...manifest.packages]
+            .sort((left, right) => left.name.localeCompare(right.name))
+            .map((entry) => ({ name: entry.name, alias: entry.alias })),
+    };
+    return `${JSON.stringify(ordered, null, 2)}\n`;
+}
+/** Parse and validate a manifest, naming what is wrong rather than throwing a cast error. */
+function parseManifest(contents, location = exports.MANIFEST_FILE) {
+    let raw;
+    try {
+        raw = JSON.parse(contents);
+    }
+    catch (error) {
+        throw new core_1.ConfigurationError({
+            detail: `${location} is not valid JSON`,
+            cause: error,
+            meta: { location },
+        });
+    }
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        throw new core_1.ConfigurationError({ detail: `${location} must contain an object` });
+    }
+    const candidate = raw;
+    const name = requireString(candidate.name, 'name', location);
+    const engine = requireString(candidate.engine, 'engine', location);
+    const frameworkVersion = requireString(candidate.frameworkVersion, 'frameworkVersion', location);
+    return {
+        version: 1,
+        name,
+        engine: engine,
+        frameworkVersion,
+        apps: [...(candidate.apps ?? [])],
+        packages: [...(candidate.packages ?? [])],
+    };
+}
+function requireString(value, field, location) {
+    if (typeof value !== 'string') {
+        throw new core_1.ConfigurationError({
+            detail: `${location} is missing "${field}"`,
+            meta: { location, field },
+        });
+    }
+    return value;
+}
+/**
+ * Walk up from `start` looking for a workspace root.
+ *
+ * Commands can then be run from anywhere inside the workspace, which is how
+ * `--app` stays optional: the current directory usually says which app is meant.
+ */
+function findWorkspaceRoot(start) {
+    let current = (0, node_path_1.resolve)(start);
+    for (;;) {
+        if ((0, node_fs_1.existsSync)((0, node_path_1.join)(current, exports.MANIFEST_FILE)))
+            return current;
+        const parent = (0, node_path_1.dirname)(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+}
+/** Load the manifest for the workspace containing `start`. */
+async function loadWorkspace(start) {
+    const root = findWorkspaceRoot(start);
+    if (root === undefined) {
+        throw new core_1.ConfigurationError({
+            detail: `No ${exports.MANIFEST_FILE} found in this directory or any parent`,
+            meta: { start, hint: 'Run this inside a workspace, or create one with `nage create`.' },
+        });
+    }
+    const contents = await (0, promises_1.readFile)((0, node_path_1.join)(root, exports.MANIFEST_FILE), 'utf8');
+    return { root, manifest: parseManifest(contents) };
+}
+/** Which app a command targets: `--app`, or the one the cwd sits inside. */
+function resolveTargetApp(manifest, options) {
+    if (options.app !== undefined) {
+        const named = manifest.apps.find((app) => app.name === options.app);
+        if (named === undefined) {
+            throw new core_1.ConfigurationError({
+                detail: `This workspace has no app named "${options.app}"`,
+                meta: { app: options.app, available: manifest.apps.map((app) => app.name) },
+            });
+        }
+        return named;
+    }
+    const relativeCwd = (0, node_path_1.resolve)(options.cwd)
+        .slice((0, node_path_1.resolve)(options.root).length + 1)
+        .split('\\')
+        .join('/');
+    const segments = relativeCwd.split('/');
+    if (segments[0] === 'apps' && segments[1] !== undefined) {
+        const inferred = manifest.apps.find((app) => app.name === segments[1]);
+        if (inferred !== undefined)
+            return inferred;
+    }
+    if (manifest.apps.length === 1 && manifest.apps[0] !== undefined)
+        return manifest.apps[0];
+    throw new core_1.ConfigurationError({
+        detail: manifest.apps.length === 0
+            ? 'This workspace has no apps yet; add one with `nage new app <name>`'
+            : 'Several apps exist and the current directory is not inside one — pass --app <name>',
+        meta: { available: manifest.apps.map((app) => app.name) },
+    });
+}
+/** Next free port, so two apps never default to the same one. */
+function nextAvailablePort(manifest) {
+    const used = new Set(manifest.apps.map((app) => app.port));
+    let port = exports.DEFAULT_PORT;
+    while (used.has(port))
+        port += 1;
+    return port;
+}
+//# sourceMappingURL=manifest.js.map

package/dist/workspace/wiring.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Keeping the workspace's own files in step (PLAN.md §10.5).
+ *
+ * Adding an app or a shared package touches four files besides the new
+ * directory: `nage.workspace.json`, `pnpm-workspace.yaml`, `turbo.json` and
+ * `tsconfig.base.json` path aliases. These functions produce the updated
+ * contents; the caller writes them through `commitFileTree`, so either all five
+ * changes land or none do.
+ *
+ * Each is idempotent — running `new app` twice for the same name adds nothing
+ * the second time, which is what makes a failed-then-retried command safe.
+ */
+/** Add a glob to `pnpm-workspace.yaml`'s `packages:` list if it is absent. */
+export declare function addWorkspaceGlob(contents: string, glob: string): string;
+/** Add a path alias to `tsconfig.base.json`, so `@app/domain` resolves. */
+export declare function addPathAlias(contents: string, alias: string, target: string): string;
+/** Remove an alias and its wildcard — the reverse, for `remove app`. */
+export declare function removePathAlias(contents: string, alias: string): string;
+/**
+ * Register a project reference in the root solution tsconfig, keeping the list
+ * sorted so two `new app` runs in either order produce the same file.
+ */
+export declare function addProjectReference(contents: string, path: string): string;
+export declare function removeProjectReference(contents: string, path: string): string;
+/**
+ * Declare a turbo task input for an app.
+ *
+ * Turbo discovers packages from the pnpm workspace, so nothing is required per
+ * app; this only records app-specific outputs (a Dockerfile build context, say)
+ * when a preset needs them.
+ */
+export declare function addTurboTaskOutput(contents: string, task: string, output: string): string;
+//# sourceMappingURL=wiring.d.ts.map

package/dist/workspace/wiring.js

@@ -0,0 +1,112 @@
+"use strict";
+/**
+ * Keeping the workspace's own files in step (PLAN.md §10.5).
+ *
+ * Adding an app or a shared package touches four files besides the new
+ * directory: `nage.workspace.json`, `pnpm-workspace.yaml`, `turbo.json` and
+ * `tsconfig.base.json` path aliases. These functions produce the updated
+ * contents; the caller writes them through `commitFileTree`, so either all five
+ * changes land or none do.
+ *
+ * Each is idempotent — running `new app` twice for the same name adds nothing
+ * the second time, which is what makes a failed-then-retried command safe.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addWorkspaceGlob = addWorkspaceGlob;
+exports.addPathAlias = addPathAlias;
+exports.removePathAlias = removePathAlias;
+exports.addProjectReference = addProjectReference;
+exports.removeProjectReference = removeProjectReference;
+exports.addTurboTaskOutput = addTurboTaskOutput;
+const core_1 = require("@nage-api/core");
+/** Add a glob to `pnpm-workspace.yaml`'s `packages:` list if it is absent. */
+function addWorkspaceGlob(contents, glob) {
+    const lines = contents.split('\n');
+    const packagesIndex = lines.findIndex((line) => /^packages:\s*$/.test(line));
+    if (packagesIndex === -1) {
+        throw new core_1.ConfigurationError({
+            detail: 'pnpm-workspace.yaml has no `packages:` list to extend',
+            meta: { glob },
+        });
+    }
+    let end = packagesIndex + 1;
+    while (end < lines.length && /^\s*-\s/.test(lines[end] ?? ''))
+        end += 1;
+    const entries = lines.slice(packagesIndex + 1, end);
+    const quoted = `  - '${glob}'`;
+    if (entries.some((entry) => entry.trim() === `- '${glob}'` || entry.trim() === `- "${glob}"`)) {
+        return contents;
+    }
+    return [...lines.slice(0, end), quoted, ...lines.slice(end)].join('\n');
+}
+/** Add a path alias to `tsconfig.base.json`, so `@app/domain` resolves. */
+function addPathAlias(contents, alias, target) {
+    const config = parseJson(contents, 'tsconfig.base.json');
+    const compilerOptions = (config['compilerOptions'] ?? {});
+    const paths = { ...(compilerOptions['paths'] ?? {}) };
+    paths[alias] = [target];
+    paths[`${alias}/*`] = [`${target.replace(/\/index\.ts$/, '')}/*`];
+    const ordered = Object.fromEntries(Object.entries(paths).sort(([left], [right]) => left.localeCompare(right)));
+    return `${JSON.stringify({ ...config, compilerOptions: { ...compilerOptions, paths: ordered } }, null, 2)}\n`;
+}
+/** Remove an alias and its wildcard — the reverse, for `remove app`. */
+function removePathAlias(contents, alias) {
+    const config = parseJson(contents, 'tsconfig.base.json');
+    const compilerOptions = (config['compilerOptions'] ?? {});
+    const removed = new Set([alias, `${alias}/*`]);
+    const paths = Object.fromEntries(Object.entries((compilerOptions['paths'] ?? {})).filter(([key]) => !removed.has(key)));
+    return `${JSON.stringify({ ...config, compilerOptions: { ...compilerOptions, paths } }, null, 2)}\n`;
+}
+/**
+ * Register a project reference in the root solution tsconfig, keeping the list
+ * sorted so two `new app` runs in either order produce the same file.
+ */
+function addProjectReference(contents, path) {
+    const config = parseJson(contents, 'tsconfig.json');
+    const references = [...(config['references'] ?? [])];
+    if (references.some((reference) => reference.path === path))
+        return contents;
+    references.push({ path });
+    references.sort((left, right) => left.path.localeCompare(right.path));
+    return `${JSON.stringify({ ...config, references }, null, 2)}\n`;
+}
+function removeProjectReference(contents, path) {
+    const config = parseJson(contents, 'tsconfig.json');
+    const references = (config['references'] ?? []).filter((reference) => reference.path !== path);
+    return `${JSON.stringify({ ...config, references }, null, 2)}\n`;
+}
+/**
+ * Declare a turbo task input for an app.
+ *
+ * Turbo discovers packages from the pnpm workspace, so nothing is required per
+ * app; this only records app-specific outputs (a Dockerfile build context, say)
+ * when a preset needs them.
+ */
+function addTurboTaskOutput(contents, task, output) {
+    const config = parseJson(contents, 'turbo.json');
+    const tasks = { ...(config['tasks'] ?? {}) };
+    const existing = { ...(tasks[task] ?? {}) };
+    const outputs = [...(existing['outputs'] ?? [])];
+    if (!outputs.includes(output))
+        outputs.push(output);
+    outputs.sort();
+    tasks[task] = { ...existing, outputs };
+    return `${JSON.stringify({ ...config, tasks }, null, 2)}\n`;
+}
+function parseJson(contents, location) {
+    try {
+        const parsed = JSON.parse(contents);
+        if (typeof parsed !== 'object' || parsed === null) {
+            throw new Error('not an object');
+        }
+        return parsed;
+    }
+    catch (error) {
+        throw new core_1.ConfigurationError({
+            detail: `${location} could not be parsed; the workspace may have been edited by hand`,
+            cause: error,
+            meta: { location },
+        });
+    }
+}
+//# sourceMappingURL=wiring.js.map

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@nage-api/cli",
+  "version": "1.0.0-beta.2",
+  "description": "The nage CLI — scaffold and manage a @nage-api workspace, its apps, packages and resources",
+  "license": "Apache-2.0",
+  "type": "commonjs",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "nage": "./dist/main.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "!dist/.tsbuildinfo",
+    "!dist/**/*.map",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nage-api/contracts": "1.0.0-beta.2",
+    "@nage-api/core": "1.0.0-beta.2"
+  },
+  "devDependencies": {
+    "@swc/core": "1.15.47",
+    "@types/node": "22.20.1",
+    "@vitest/coverage-v8": "4.1.10",
+    "rimraf": "6.1.3",
+    "typescript": "5.9.3",
+    "unplugin-swc": "1.5.11",
+    "vitest": "4.1.10"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.build.json",
+    "clean": "rimraf dist .turbo",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}