@procedures/cue 0.0.0-stage → 0.2.0

package/src/module.ts

@@ -0,0 +1,158 @@
+/**
+ * Module (no side effects): the procedures of this package as data, for `createRegistry()`.
+ *
+ * Procedure Registration for cue operations
+ *
+ * Registers cue.* procedures with the client system.
+ * This file is referenced by package.json's client.procedures field.
+ */
+
+import { createProcedure, zodAdapter, defineModule, type ProcedureModule, PROCEDURE_REGISTRY, registerModules, type ProcedureRegistry } from "@procedures/client";
+import fsModule from "@procedures/fs/module";
+import { cueInit } from "./procedures/cue/init.js";
+import { cueAdd } from "./procedures/cue/add.js";
+import { cueRemove } from "./procedures/cue/remove.js";
+import { cueGenerate } from "./procedures/cue/generate.js";
+import { cueValidate } from "./procedures/cue/validate.js";
+import {
+  CueInitInputSchema,
+  CueAddInputSchema,
+  CueRemoveInputSchema,
+  CueGenerateInputSchema,
+  CueValidateInputSchema,
+  type CueInitInput,
+  type CueInitOutput,
+  type CueAddInput,
+  type CueAddOutput,
+  type CueRemoveInput,
+  type CueRemoveOutput,
+  type CueGenerateInput,
+  type CueGenerateOutput,
+  type CueValidateInput,
+  type CueValidateOutput,
+  CueInitOutputSchema,
+  CueAddOutputSchema,
+  CueRemoveOutputSchema,
+  CueGenerateOutputSchema,
+  CueValidateOutputSchema,
+} from "./types.js";
+
+// =============================================================================
+// Procedure Definitions
+// =============================================================================
+
+const cueInitProcedure = createProcedure()
+  .path(["cue", "init"])
+  .input(zodAdapter<CueInitInput>(CueInitInputSchema))
+  .output(zodAdapter<CueInitOutput>(CueInitOutputSchema))
+  .meta({
+    description: "Initialize dependencies.json with a preset",
+    calls: ["fs.exists", "fs.read", "fs.write", "fs.mkdir"],
+    // With `force`, it overwrites dependencies.json. A second call writes the same preset again.
+    effects: { reads: ["fs"], writes: ["fs"], idempotent: true },
+    args: [],
+    shorts: { preset: "p", force: "f", cwd: "C" },
+    output: "json",
+  })
+  .handler(async (input: CueInitInput, ctx): Promise<CueInitOutput> => {
+    return cueInit(input, ctx);
+  })
+  .build();
+
+const cueAddProcedure = createProcedure()
+  .path(["cue", "add"])
+  .input(zodAdapter<CueAddInput>(CueAddInputSchema))
+  .output(zodAdapter<CueAddOutput>(CueAddOutputSchema))
+  .meta({
+    description: "Add a feature to dependencies.json",
+    calls: ["fs.exists", "fs.read", "fs.write"],
+    // It writes dependencies.json again with only `$schema` and `dependencies`. Other fields go.
+    effects: { reads: ["fs"], writes: ["fs"], idempotent: true },
+    args: ["feature"],
+    shorts: { cwd: "C" },
+    output: "json",
+  })
+  .handler(async (input: CueAddInput, ctx): Promise<CueAddOutput> => {
+    return cueAdd(input, ctx);
+  })
+  .build();
+
+const cueRemoveProcedure = createProcedure()
+  .path(["cue", "remove"])
+  .input(zodAdapter<CueRemoveInput>(CueRemoveInputSchema))
+  .output(zodAdapter<CueRemoveOutput>(CueRemoveOutputSchema))
+  .meta({
+    description: "Remove a feature from dependencies.json",
+    calls: ["fs.exists", "fs.read", "fs.write"],
+    effects: { reads: ["fs"], writes: ["fs"], idempotent: true },
+    args: ["feature"],
+    shorts: { cwd: "C" },
+    output: "json",
+  })
+  .handler(async (input: CueRemoveInput, ctx): Promise<CueRemoveOutput> => {
+    return cueRemove(input, ctx);
+  })
+  .build();
+
+const cueGenerateProcedure = createProcedure()
+  .path(["cue", "generate"])
+  .input(zodAdapter<CueGenerateInput>(CueGenerateInputSchema))
+  .output(zodAdapter<CueGenerateOutput>(CueGenerateOutputSchema))
+  .meta({
+    description: "Generate config files from dependencies.json",
+    calls: ["fs.exists", "fs.read", "fs.write", "fs.mkdir"],
+    // The cue program evaluates the CUE files of @mark1russell7/cue, not code of the project.
+    // The procedure rewrites package.json, tsconfig.json and .gitignore.
+    effects: { reads: ["fs"], writes: ["fs"], idempotent: true },
+    args: [],
+    shorts: { cwd: "C" },
+    output: "json",
+  })
+  .handler(async (input: CueGenerateInput, ctx): Promise<CueGenerateOutput> => {
+    return cueGenerate(input, ctx);
+  })
+  .build();
+
+const cueValidateProcedure = createProcedure()
+  .path(["cue", "validate"])
+  .input(zodAdapter<CueValidateInput>(CueValidateInputSchema))
+  .output(zodAdapter<CueValidateOutput>(CueValidateOutputSchema))
+  .meta({
+    description: "Validate dependencies.json",
+    calls: ["fs.exists", "fs.read"],
+    effects: { reads: ["fs"], writes: [] },
+    args: [],
+    shorts: { cwd: "C" },
+    output: "json",
+  })
+  .handler(async (input: CueValidateInput, ctx): Promise<CueValidateOutput> => {
+    return cueValidate(input, ctx);
+  })
+  .build();
+
+// =============================================================================
+// Registration
+// =============================================================================
+
+/**
+ * The module of this package, for `createRegistry()`: its procedures as data. Importing this
+ * file registers nothing. (`register.ts` registers the same procedures in the global registry.)
+ */
+export const cueModule: ProcedureModule = defineModule("@procedures/cue", [
+    cueInitProcedure,
+    cueAddProcedure,
+    cueRemoveProcedure,
+    cueGenerateProcedure,
+    cueValidateProcedure,
+  ], [fsModule]);
+
+export default cueModule;
+
+/**
+ * This function registers the procedures of @procedures/cue, and of the modules that it requires, in
+ * a registry. The default is the global registry. Importing this file registers nothing: the
+ * `./register` entry starts this function (ARCHITECTURE-PROPOSALS-2026-10, P9).
+ */
+export function registerCueProcedures(registry: ProcedureRegistry = PROCEDURE_REGISTRY): void {
+  registerModules(registry, [cueModule]);
+}

package/src/procedures/cue/add.ts

@@ -0,0 +1,80 @@
+/**
+ * cue.add procedure
+ *
+ * Add a feature to dependencies.json.
+ * Uses ctx.client.call() for file system operations (dogfooding).
+ */
+
+import type { ProcedureContext } from "@procedures/client";
+import type { CueAddInput, CueAddOutput } from "../../types.js";
+import {
+  loadFeatures,
+  loadDependencies,
+  saveDependencies,
+} from "../../shared.js";
+
+/**
+ * Add a feature to dependencies.json
+ */
+export async function cueAdd(
+  input: CueAddInput,
+  ctx: ProcedureContext
+): Promise<CueAddOutput> {
+  const projectPath = input.cwd ?? process.cwd();
+  const feature = input.feature;
+
+  // Load features manifest
+  const manifest = await loadFeatures(ctx);
+  if (!manifest) {
+    return {
+      success: false,
+      feature,
+      added: false,
+      error: "Could not load features.json from @mark1russell7/cue package",
+    };
+  }
+
+  // Validate feature exists
+  if (!manifest.features[feature]) {
+    const available = Object.keys(manifest.features).join(", ");
+    return {
+      success: false,
+      feature,
+      added: false,
+      error: `Unknown feature: ${feature}. Available: ${available}`,
+    };
+  }
+
+  // Load current dependencies
+  const deps = await loadDependencies(projectPath, ctx) ?? [];
+
+  // Check if already present
+  if (deps.includes(feature)) {
+    return {
+      success: true,
+      feature,
+      added: false,
+      message: `Feature '${feature}' is already in dependencies`,
+    };
+  }
+
+  // Add feature and save
+  deps.push(feature);
+  const saved = await saveDependencies(deps, projectPath, ctx);
+
+  if (!saved) {
+    return {
+      success: false,
+      feature,
+      added: false,
+      error: "Failed to write dependencies.json",
+    };
+  }
+
+  return {
+    success: true,
+    feature,
+    added: true,
+    message: `Added '${feature}' to dependencies.json`,
+  };
+}

package/src/procedures/cue/generate.ts

@@ -0,0 +1,245 @@
+/**
+ * cue.generate procedure
+ *
+ * Generate config files (package.json, tsconfig.json, .gitignore).
+ * Uses ctx.client.call() for file system operations (dogfooding).
+ * Runs the cue program through runCommand of client-shell (async, no shell).
+ */
+
+import { resolve } from "node:path";
+import type { ProcedureContext } from "@procedures/client";
+import type { CueGenerateInput, CueGenerateOutput } from "../../types.js";
+import {
+  loadFeatures,
+  loadDependencies,
+  resolveFeatures,
+  checkCue,
+  runCue,
+  determineTsconfig,
+  featureToFieldName,
+  packageRoot,
+  fileExists,
+  readJson,
+  writeJson,
+  writeFile,
+  mkdir,
+} from "../../shared.js";
+
+interface PackageJson {
+  $schema?: string;
+  name?: string;
+  version?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Keys that describe a package's own entry points. The package owns them: a generated value
+ * is only a default for a package that has none. (BUGS-2026-07 H33: generate replaced a
+ * multi-entry "exports" with the generated "." entry, and dropped bin and sideEffects.)
+ * Policy keys, for example "engines", still come from the generator.
+ */
+const PACKAGE_OWNED_KEYS: ReadonlySet<string> = new Set(["exports", "main", "types", "bin", "sideEffects"]);
+
+/**
+ * Generate package.json via CUE evaluation
+ */
+async function generatePackageJson(
+  resolvedFeatures: string[],
+  existingPkg: PackageJson | null,
+  ctx: ProcedureContext
+): Promise<PackageJson | null> {
+  const configDir = resolve(packageRoot, "npm/package");
+
+  // Build list of CUE files to evaluate
+  const files: string[] = ["base.cue"];
+  for (const feature of resolvedFeatures) {
+    const fieldName = featureToFieldName(feature);
+    const cuePath = resolve(configDir, `${fieldName}.cue`);
+    if (await fileExists(cuePath, ctx)) {
+      files.push(`${fieldName}.cue`);
+    }
+  }
+
+  // Run cue eval
+  const result = await runCue(["eval", ...files, "-e", "output", "--out", "json"], { cwd: configDir, signal: ctx.signal });
+
+  if (!result.success) {
+    throw new Error(`cue eval failed for package.json: ${(result.stderr || result.stdout || "").trim()}`);
+  }
+
+  const generated = JSON.parse(result.stdout) as PackageJson;
+
+  // Merge with existing package.json
+  const pkg: PackageJson = { ...existingPkg };
+
+  for (const [key, value] of Object.entries(generated)) {
+    if (key === "name" || key === "version" || key === "description") {
+      if (!pkg[key]) pkg[key] = value as string;
+    } else if (key === "devDependencies" || key === "peerDependencies" || key === "scripts") {
+      pkg[key] = { ...(value as Record<string, unknown>), ...(pkg[key] as Record<string, unknown> ?? {}) };
+    } else if (key === "files" && Array.isArray(value) && Array.isArray(pkg[key])) {
+      const merged = [...(value as string[])];
+      for (const item of pkg[key] as string[]) {
+        if (!merged.includes(item)) merged.push(item);
+      }
+      pkg[key] = merged;
+    } else if (PACKAGE_OWNED_KEYS.has(key)) {
+      if (pkg[key] === undefined) pkg[key] = value;
+    } else {
+      pkg[key] = value;
+    }
+  }
+
+  // Ensure $schema is first
+  const ordered: PackageJson = { $schema: "https://json.schemastore.org/package" };
+  for (const [key, value] of Object.entries(pkg)) {
+    if (key !== "$schema") ordered[key] = value;
+  }
+
+  return ordered;
+}
+
+/**
+ * Generate .gitignore via CUE evaluation
+ */
+async function generateGitignore(
+  resolvedFeatures: string[],
+  ctx: ProcedureContext
+): Promise<string | null> {
+  const configDir = resolve(packageRoot, "git/ignore");
+
+  const files: string[] = ["base.cue"];
+  for (const feature of resolvedFeatures) {
+    const cuePath = resolve(configDir, `${feature}.cue`);
+    if (await fileExists(cuePath, ctx)) {
+      files.push(`${feature}.cue`);
+    }
+  }
+
+  const result = await runCue(["eval", ...files, "-e", "patterns", "--out", "json"], { cwd: configDir, signal: ctx.signal });
+
+  if (!result.success) {
+    throw new Error(`cue eval failed for .gitignore: ${(result.stderr || result.stdout || "").trim()}`);
+  }
+
+  const patterns = JSON.parse(result.stdout) as string[];
+  return patterns.join("\n") + "\n";
+}
+
+/**
+ * Setup cue.mod directory
+ */
+async function setupCueMod(projectPath: string, ctx: ProcedureContext): Promise<void> {
+  const cueModPath = resolve(projectPath, "cue.mod");
+  if (!(await fileExists(cueModPath, ctx))) {
+    await mkdir(cueModPath, ctx);
+  }
+
+  await writeFile(
+    resolve(cueModPath, "module.cue"),
+    `module: "project.local"
+language: {
+\tversion: "v0.15.1"
+}
+`,
+    ctx
+  );
+}
+
+/**
+ * Generate config files from dependencies.json
+ */
+export async function cueGenerate(
+  input: CueGenerateInput,
+  ctx: ProcedureContext
+): Promise<CueGenerateOutput> {
+  const projectPath = input.cwd ?? process.cwd();
+  const generated: string[] = [];
+
+  // Check CUE is installed
+  if (!(await checkCue(ctx.signal))) {
+    return {
+      success: false,
+      resolvedFeatures: [],
+      generated: [],
+      error: "CUE is not installed. Install from: https://cuelang.org/docs/install/",
+    };
+  }
+
+  // Load features manifest
+  const manifest = await loadFeatures(ctx);
+  if (!manifest) {
+    return {
+      success: false,
+      resolvedFeatures: [],
+      generated: [],
+      error: "Could not load features.json from @mark1russell7/cue package",
+    };
+  }
+
+  // Load dependencies
+  const deps = await loadDependencies(projectPath, ctx);
+  if (!deps) {
+    return {
+      success: false,
+      resolvedFeatures: [],
+      generated: [],
+      error: "No dependencies.json found. Run cue.init first.",
+    };
+  }
+
+  // Resolve transitive dependencies
+  const resolvedFeatures = resolveFeatures(deps, manifest);
+
+  // Load existing package.json
+  const existingPkg = await readJson<PackageJson>(resolve(projectPath, "package.json"), ctx);
+
+  // A failed cue eval is an error of the whole call, not a silently skipped file
+  // (BUGS-2026-07 M36: the procedure reported success with nothing generated).
+  try {
+    // Generate package.json
+    const packageJson = await generatePackageJson(resolvedFeatures, existingPkg, ctx);
+    if (packageJson) {
+      await writeJson(resolve(projectPath, "package.json"), packageJson, ctx);
+      generated.push("package.json");
+    }
+
+    // Generate tsconfig.json if ts feature is present
+    if (resolvedFeatures.includes("ts")) {
+      const tsconfigName = determineTsconfig(resolvedFeatures);
+      const tsconfig = {
+        $schema: "https://json.schemastore.org/tsconfig",
+        extends: `@mark1russell7/cue/ts/config/${tsconfigName}.json`,
+      };
+      await writeJson(resolve(projectPath, "tsconfig.json"), tsconfig, ctx);
+      generated.push("tsconfig.json");
+    }
+
+    // Generate .gitignore
+    const gitignoreContent = await generateGitignore(resolvedFeatures, ctx);
+    if (gitignoreContent) {
+      await writeFile(resolve(projectPath, ".gitignore"), gitignoreContent, ctx);
+      generated.push(".gitignore");
+    }
+
+    // Setup cue.mod if cue feature is present
+    if (resolvedFeatures.includes("cue")) {
+      await setupCueMod(projectPath, ctx);
+      generated.push("cue.mod/");
+    }
+  } catch (error) {
+    return {
+      success: false,
+      resolvedFeatures,
+      generated,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+
+  return {
+    success: true,
+    resolvedFeatures,
+    generated,
+    message: `Generated ${generated.length} files`,
+  };
+}

package/src/procedures/cue/index.ts

@@ -0,0 +1,5 @@
+export { cueInit } from "./init.js";
+export { cueAdd } from "./add.js";
+export { cueRemove } from "./remove.js";
+export { cueGenerate } from "./generate.js";
+export { cueValidate } from "./validate.js";

package/src/procedures/cue/init.ts

@@ -0,0 +1,98 @@
+/**
+ * cue.init procedure
+ *
+ * Initialize dependencies.json with a preset.
+ * Uses ctx.client.call() for file system operations (dogfooding).
+ */
+
+import { resolve } from "node:path";
+import type { ProcedureContext } from "@procedures/client";
+import type { CueInitInput, CueInitOutput } from "../../types.js";
+import {
+  loadFeatures,
+  saveDependencies,
+  fileExists,
+  mkdir,
+  writeFile,
+} from "../../shared.js";
+
+/**
+ * Initialize a project with dependencies.json
+ */
+export async function cueInit(
+  input: CueInitInput,
+  ctx: ProcedureContext
+): Promise<CueInitOutput> {
+  const projectPath = input.cwd ?? process.cwd();
+  const presetName = input.preset ?? "lib";
+  const created: string[] = [];
+
+  // Load features manifest
+  const manifest = await loadFeatures(ctx);
+  if (!manifest) {
+    return {
+      success: false,
+      preset: presetName,
+      created: [],
+      error: "Could not load features.json from @mark1russell7/cue package",
+    };
+  }
+
+  // Validate preset
+  const preset = manifest.presets[presetName];
+  if (!preset) {
+    const available = Object.keys(manifest.presets).join(", ");
+    return {
+      success: false,
+      preset: presetName,
+      created: [],
+      error: `Unknown preset: ${presetName}. Available: ${available}`,
+    };
+  }
+
+  // Check if dependencies.json exists
+  const depsPath = resolve(projectPath, "dependencies.json");
+  if (await fileExists(depsPath, ctx)) {
+    if (!input.force) {
+      return {
+        success: true,
+        preset: presetName,
+        created: [],
+        message: "dependencies.json already exists (use force: true to overwrite)",
+      };
+    }
+  }
+
+  // Create dependencies.json
+  const saved = await saveDependencies(preset, projectPath, ctx);
+  if (!saved) {
+    return {
+      success: false,
+      preset: presetName,
+      created: [],
+      error: "Failed to write dependencies.json",
+    };
+  }
+  created.push("dependencies.json");
+
+  // Create src directory if needed
+  const srcPath = resolve(projectPath, "src");
+  if (!(await fileExists(srcPath, ctx))) {
+    await mkdir(srcPath, ctx);
+    created.push("src/");
+  }
+
+  // Create src/index.ts if needed
+  const indexPath = resolve(projectPath, "src", "index.ts");
+  if (!(await fileExists(indexPath, ctx))) {
+    await writeFile(indexPath, "// Entry point\nexport {};\n", ctx);
+    created.push("src/index.ts");
+  }
+
+  return {
+    success: true,
+    preset: presetName,
+    created,
+    message: `Initialized with preset '${presetName}'. Run cue.generate to create config files.`,
+  };
+}

package/src/procedures/cue/remove.ts

@@ -0,0 +1,64 @@
+/**
+ * cue.remove procedure
+ *
+ * Remove a feature from dependencies.json.
+ * Uses ctx.client.call() for file system operations (dogfooding).
+ */
+
+import type { ProcedureContext } from "@procedures/client";
+import type { CueRemoveInput, CueRemoveOutput } from "../../types.js";
+import { loadDependencies, saveDependencies } from "../../shared.js";
+
+/**
+ * Remove a feature from dependencies.json
+ */
+export async function cueRemove(
+  input: CueRemoveInput,
+  ctx: ProcedureContext
+): Promise<CueRemoveOutput> {
+  const projectPath = input.cwd ?? process.cwd();
+  const feature = input.feature;
+
+  // Load current dependencies
+  const deps = await loadDependencies(projectPath, ctx);
+
+  if (!deps) {
+    return {
+      success: false,
+      feature,
+      removed: false,
+      error: "No dependencies.json found. Run cue.init first.",
+    };
+  }
+
+  // Check if feature is present
+  const idx = deps.indexOf(feature);
+  if (idx === -1) {
+    return {
+      success: true,
+      feature,
+      removed: false,
+      message: `Feature '${feature}' is not in dependencies`,
+    };
+  }
+
+  // Remove feature and save
+  deps.splice(idx, 1);
+  const saved = await saveDependencies(deps, projectPath, ctx);
+
+  if (!saved) {
+    return {
+      success: false,
+      feature,
+      removed: false,
+      error: "Failed to write dependencies.json",
+    };
+  }
+
+  return {
+    success: true,
+    feature,
+    removed: true,
+    message: `Removed '${feature}' from dependencies.json`,
+  };
+}