@procedures/cue 0.0.0-stage → 0.2.0

package/src/procedures/cue/validate.ts

@@ -0,0 +1,96 @@
+/**
+ * cue.validate procedure
+ *
+ * Validate dependencies.json against schema.
+ * Uses ctx.client.call() for file system operations (dogfooding).
+ */
+
+import { resolve } from "node:path";
+import type { ProcedureContext } from "@procedures/client";
+import type { CueValidateInput, CueValidateOutput } from "../../types.js";
+import {
+  loadFeatures,
+  loadDependencies,
+  checkCue,
+  runCue,
+  packageRoot,
+  fileExists,
+} from "../../shared.js";
+
+/**
+ * Validate dependencies.json
+ */
+export async function cueValidate(
+  input: CueValidateInput,
+  ctx: ProcedureContext
+): Promise<CueValidateOutput> {
+  const projectPath = input.cwd ?? process.cwd();
+  const errors: string[] = [];
+
+  // Load dependencies
+  const deps = await loadDependencies(projectPath, ctx);
+  if (!deps) {
+    return {
+      success: false,
+      valid: false,
+      features: [],
+      errors: ["No dependencies.json found. Run cue.init first."],
+    };
+  }
+
+  // Load features manifest
+  const manifest = await loadFeatures(ctx);
+  if (!manifest) {
+    return {
+      success: false,
+      valid: false,
+      features: deps,
+      errors: ["Could not load features.json from @mark1russell7/cue package"],
+    };
+  }
+
+  // Validate each feature exists
+  for (const feature of deps) {
+    if (!manifest.features[feature]) {
+      errors.push(`Unknown feature: '${feature}'`);
+    }
+  }
+
+  if (errors.length > 0) {
+    return {
+      success: true,
+      valid: false,
+      features: deps,
+      errors,
+      message: `Validation failed with ${errors.length} error(s)`,
+    };
+  }
+
+  // If CUE is available, validate against schema
+  if (await checkCue(ctx.signal)) {
+    const schemaPath = resolve(packageRoot, "dependencies/schema.cue");
+    if (await fileExists(schemaPath, ctx)) {
+      const depsPath = resolve(projectPath, "dependencies.json");
+      const result = await runCue(["vet", "-d", "#Dependencies", schemaPath, depsPath], { signal: ctx.signal });
+
+      if (!result.success) {
+        errors.push(`CUE schema validation failed: ${result.stderr || result.stdout}`);
+        return {
+          success: true,
+          valid: false,
+          features: deps,
+          errors,
+          message: "CUE schema validation failed",
+        };
+      }
+    }
+  }
+
+  return {
+    success: true,
+    valid: true,
+    features: deps,
+    errors: [],
+    message: "Validation passed",
+  };
+}

package/src/register.ts

@@ -0,0 +1,11 @@
+/**
+ * Importing this file registers the procedures of @procedures/cue, and of the modules that it
+ * requires, in the global registry: `import "@procedures/cue/register"`. The package root and the
+ * `./module` entry register nothing (ARCHITECTURE-PROPOSALS-2026-10, P9).
+ */
+
+import { registerCueProcedures } from "./module.js";
+
+export * from "./module.js";
+
+registerCueProcedures();

package/src/shared.ts

@@ -0,0 +1,216 @@
+/**
+ * Shared utilities for cue procedures
+ *
+ * Uses ctx.client.call() for file system operations (dogfooding).
+ *
+ * A file operation that fails is an error of the call. Only a missing file is a normal result.
+ * (Before, each helper turned every error into "missing": with no fs.* procedures in the host,
+ * cue.validate answered "No dependencies.json found", deep dive WRP-3.)
+ */
+
+import { createRequire } from "node:module";
+import { dirname, resolve } from "node:path";
+import type { ProcedureContext } from "@procedures/client";
+import { runCommand, type CommandResult } from "@procedures/shell/command";
+import type { FeaturesManifest, DependenciesJson } from "./types.js";
+
+// Constants
+// The root of the installed @mark1russell7/cue package (its CUE files and features.json).
+// Resolve it like an import, so it works wherever the package manager put it
+// (BUGS-2026-07 H32: a hard-coded node_modules path only worked for a dev install).
+const require = createRequire(import.meta.url);
+export const packageRoot: string = dirname(require.resolve("@mark1russell7/cue/features.json"));
+
+// Tsconfig priority: later features override earlier (most specific wins)
+export const TSCONFIG_PRIORITY: readonly string[] = ["ts", "node", "node-cjs", "vite", "react"] as const;
+
+// =============================================================================
+// FS Procedure Output Types
+// =============================================================================
+
+interface FsExistsOutput {
+  exists: boolean;
+  path: string;
+}
+
+interface FsReadOutput {
+  path: string;
+  content: string;
+}
+
+interface FsWriteOutput {
+  path: string;
+  written: number;
+}
+
+interface FsMkdirOutput {
+  path: string;
+  created: boolean;
+}
+
+// =============================================================================
+// File System Helpers (using ctx.client.call)
+// =============================================================================
+
+export async function fileExists(path: string, ctx: ProcedureContext): Promise<boolean> {
+  const result = await ctx.client.call<{ path: string }, FsExistsOutput>(
+    ["fs", "exists"],
+    { path }
+  );
+  return result.exists;
+}
+
+/** The content of a file, or null when the file does not exist. Other failures throw. */
+export async function readFile(path: string, ctx: ProcedureContext): Promise<string | null> {
+  if (!(await fileExists(path, ctx))) return null;
+  const result = await ctx.client.call<{ path: string; encoding?: string }, FsReadOutput>(
+    ["fs", "read"],
+    { path, encoding: "utf-8" }
+  );
+  return result.content;
+}
+
+export async function writeFile(path: string, content: string, ctx: ProcedureContext): Promise<boolean> {
+  try {
+    await ctx.client.call<{ path: string; content: string }, FsWriteOutput>(
+      ["fs", "write"],
+      { path, content }
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function mkdir(path: string, ctx: ProcedureContext): Promise<boolean> {
+  try {
+    await ctx.client.call<{ path: string; recursive?: boolean }, FsMkdirOutput>(
+      ["fs", "mkdir"],
+      { path, recursive: true }
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// =============================================================================
+// JSON Helpers
+// =============================================================================
+
+/** The JSON content of a file, or null when the file does not exist. Text that is not JSON throws. */
+export async function readJson<T>(path: string, ctx: ProcedureContext): Promise<T | null> {
+  const content = await readFile(path, ctx);
+  if (content === null) return null;
+  try {
+    return JSON.parse(content) as T;
+  } catch (error) {
+    throw new Error(`${path} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+export async function writeJson<T>(path: string, data: T, ctx: ProcedureContext): Promise<boolean> {
+  const content = JSON.stringify(data, null, 2) + "\n";
+  return writeFile(path, content, ctx);
+}
+
+// =============================================================================
+// Core Functions
+// =============================================================================
+
+export async function loadFeatures(ctx: ProcedureContext): Promise<FeaturesManifest | null> {
+  const featuresPath = resolve(packageRoot, "features.json");
+  return readJson<FeaturesManifest>(featuresPath, ctx);
+}
+
+export async function loadDependencies(
+  projectPath: string,
+  ctx: ProcedureContext
+): Promise<string[] | null> {
+  const depsPath = resolve(projectPath, "dependencies.json");
+  const content = await readJson<DependenciesJson | string[]>(depsPath, ctx);
+
+  if (!content) return null;
+
+  if (Array.isArray(content)) {
+    return content;
+  }
+
+  if (content.dependencies && Array.isArray(content.dependencies)) {
+    return content.dependencies;
+  }
+
+  return null;
+}
+
+export async function saveDependencies(
+  deps: string[],
+  projectPath: string,
+  ctx: ProcedureContext
+): Promise<boolean> {
+  const depsJson: DependenciesJson = {
+    $schema: "./node_modules/@mark1russell7/cue/dependencies/schema.json",
+    dependencies: deps,
+  };
+  return writeJson(resolve(projectPath, "dependencies.json"), depsJson, ctx);
+}
+
+// Flood-fill resolve all transitive dependencies
+export function resolveFeatures(requested: string[], manifest: FeaturesManifest): string[] {
+  const resolved = new Set<string>();
+  const queue = [...requested];
+
+  while (queue.length > 0) {
+    const feature = queue.shift()!;
+    if (resolved.has(feature)) continue;
+
+    const featureDef = manifest.features[feature];
+    if (!featureDef) continue;
+
+    resolved.add(feature);
+
+    for (const dep of featureDef.dependencies) {
+      if (!resolved.has(dep)) {
+        queue.push(dep);
+      }
+    }
+  }
+
+  return Array.from(resolved);
+}
+
+// Map feature name to CUE file field name (handle vite-react -> viteReact)
+export function featureToFieldName(feature: string): string {
+  if (feature === "vite-react") return "viteReact";
+  return feature;
+}
+
+// =============================================================================
+// CUE Evaluation
+// =============================================================================
+
+/**
+ * This function runs the cue program with an argument list and no shell, through `runCommand`
+ * of client-shell: async, and the signal of the call kills it (roadmap 2.2).
+ */
+export function runCue(
+  args: string[],
+  options: { cwd?: string | undefined; signal?: AbortSignal | undefined } = {}
+): Promise<CommandResult> {
+  return runCommand("cue", { args, cwd: options.cwd, signal: options.signal, timeout: 120_000 });
+}
+
+/** True when the cue program is installed. */
+export async function checkCue(signal?: AbortSignal): Promise<boolean> {
+  return (await runCue(["version"], { signal })).success;
+}
+
+export function determineTsconfig(resolvedFeatures: string[]): string {
+  let selected = "ts";
+  for (const feature of TSCONFIG_PRIORITY) {
+    if (resolvedFeatures.includes(feature)) {
+      selected = feature;
+    }
+  }
+  return selected;
+}

package/src/types.ts

@@ -0,0 +1,181 @@
+/**
+ * Types and schemas for cue procedures
+ */
+
+import { z } from "zod";
+
+// =============================================================================
+// Shared Types
+// =============================================================================
+
+export interface Feature {
+  dependencies: string[];
+}
+
+export interface FeaturesManifest {
+  features: Record<string, Feature>;
+  presets: Record<string, string[]>;
+}
+
+export interface DependenciesJson {
+  $schema?: string;
+  dependencies: string[];
+}
+
+// =============================================================================
+// cue.init
+// =============================================================================
+
+export const CueInitInputSchema: z.ZodObject<{
+  preset: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+  force: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+  cwd: z.ZodOptional<z.ZodString>;
+}> = z.object({
+  preset: z.string().optional().default("lib").describe("The preset: lib, react-lib or app"),
+  force: z.boolean().optional().default(false).describe("Write dependencies.json again when it exists"),
+  cwd: z.string().optional().describe("The folder of the package (default: the current folder)"),
+});
+
+export type CueInitInput = z.infer<typeof CueInitInputSchema>;
+
+export interface CueInitOutput {
+  success: boolean;
+  preset: string;
+  created: string[];
+  message?: string | undefined;
+  error?: string | undefined;
+}
+
+// =============================================================================
+// cue.add
+// =============================================================================
+
+export const CueAddInputSchema: z.ZodObject<{
+  feature: z.ZodString;
+  cwd: z.ZodOptional<z.ZodString>;
+}> = z.object({
+  feature: z.string().describe("The feature: git, npm, ts, node, node-cjs, react, vite, vite-react, cue or vitest"),
+  cwd: z.string().optional().describe("The folder of the package (default: the current folder)"),
+});
+
+export type CueAddInput = z.infer<typeof CueAddInputSchema>;
+
+export interface CueAddOutput {
+  success: boolean;
+  feature: string;
+  added: boolean;
+  message?: string | undefined;
+  error?: string | undefined;
+}
+
+// =============================================================================
+// cue.remove
+// =============================================================================
+
+export const CueRemoveInputSchema: z.ZodObject<{
+  feature: z.ZodString;
+  cwd: z.ZodOptional<z.ZodString>;
+}> = z.object({
+  feature: z.string().describe("The feature: git, npm, ts, node, node-cjs, react, vite, vite-react, cue or vitest"),
+  cwd: z.string().optional().describe("The folder of the package (default: the current folder)"),
+});
+
+export type CueRemoveInput = z.infer<typeof CueRemoveInputSchema>;
+
+export interface CueRemoveOutput {
+  success: boolean;
+  feature: string;
+  removed: boolean;
+  message?: string | undefined;
+  error?: string | undefined;
+}
+
+// =============================================================================
+// cue.generate
+// =============================================================================
+
+export const CueGenerateInputSchema: z.ZodObject<{
+  cwd: z.ZodOptional<z.ZodString>;
+}> = z.object({
+  cwd: z.string().optional().describe("The folder of the package (default: the current folder)"),
+});
+
+export type CueGenerateInput = z.infer<typeof CueGenerateInputSchema>;
+
+export interface CueGenerateOutput {
+  success: boolean;
+  resolvedFeatures: string[];
+  generated: string[];
+  message?: string | undefined;
+  error?: string | undefined;
+}
+
+// =============================================================================
+// cue.validate
+// =============================================================================
+
+export const CueValidateInputSchema: z.ZodObject<{
+  cwd: z.ZodOptional<z.ZodString>;
+}> = z.object({
+  cwd: z.string().optional().describe("The folder of the package (default: the current folder)"),
+});
+
+export type CueValidateInput = z.infer<typeof CueValidateInputSchema>;
+
+export interface CueValidateOutput {
+  success: boolean;
+  valid: boolean;
+  features: string[];
+  errors: string[];
+  message?: string | undefined;
+}
+
+// =============================================================================
+// Output schemas (roadmap 2.1)
+// =============================================================================
+
+// Loose objects: a field that a schema does not name stays in the result (a strict schema
+// would remove it when the output is validated).
+
+const messageField = z.string().optional().describe("A message about the result");
+const errorField = z.string().optional().describe("The reason of a failure (when success is false)");
+
+export const CueInitOutputSchema: z.ZodType<CueInitOutput> = z.looseObject({
+  success: z.boolean().describe("True when dependencies.json exists after the call"),
+  preset: z.string().describe("The preset of the new dependencies.json"),
+  created: z.array(z.string()).describe("The files that the call made"),
+  message: messageField,
+  error: errorField,
+});
+
+export const CueAddOutputSchema: z.ZodType<CueAddOutput> = z.looseObject({
+  success: z.boolean().describe("True when the feature is in dependencies.json after the call"),
+  feature: z.string().describe("The feature"),
+  added: z.boolean().describe("True when the call added the feature (false when it was there already)"),
+  message: messageField,
+  error: errorField,
+});
+
+export const CueRemoveOutputSchema: z.ZodType<CueRemoveOutput> = z.looseObject({
+  success: z.boolean().describe("True when the feature is not in dependencies.json after the call"),
+  feature: z.string().describe("The feature"),
+  removed: z.boolean().describe("True when the call removed the feature"),
+  message: messageField,
+  error: errorField,
+});
+
+export const CueGenerateOutputSchema: z.ZodType<CueGenerateOutput> = z.looseObject({
+  success: z.boolean().describe("True when every file was generated"),
+  resolvedFeatures: z.array(z.string()).describe("The features with their dependencies"),
+  generated: z.array(z.string()).describe("The files that the call wrote"),
+  message: messageField,
+  error: errorField,
+});
+
+export const CueValidateOutputSchema: z.ZodType<CueValidateOutput> = z.looseObject({
+  success: z.boolean().describe("True when the validation ran"),
+  valid: z.boolean().describe("True when dependencies.json is valid"),
+  features: z.array(z.string()).describe("The features of dependencies.json"),
+  errors: z.array(z.string()).describe("The problems that the validation found"),
+  message: messageField,
+});