@lostgradient/weft 0.2.0

package/dist/cli/codegen.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `weft codegen` subcommand executor. Reads a registry snapshot from
+ * either a live Weft server or a vendored JSON file, validates the
+ * envelope, and emits a deterministic `.d.ts` augmenting the public
+ * `'weft'` module.
+ *
+ * All user-caused failures (missing file, bad JSON, version mismatch,
+ * HTTP errors, network timeout, missing parent directory, filesystem
+ * errors) return a {@link CommandOutput} with `exitCode: 1` and a
+ * single-line stderr diagnostic. Thrown errors are reserved for
+ * programmer bugs.
+ *
+ * @module cli/codegen
+ */
+import type { CommandOutput } from './types.ts';
+/** Parsed options accepted by {@link executeCodegen}. */
+export type CodegenOptions = {
+    server?: string;
+    from?: string;
+    token?: string;
+    out: string;
+    timeoutMs: number;
+    /** When true, emit a single JSON object on stdout for machine consumers. */
+    json?: boolean;
+};
+/**
+ * Run the codegen pipeline end-to-end. Returns a {@link CommandOutput}
+ * describing the result. Never rejects for user-caused failures.
+ */
+export declare function executeCodegen(options: CodegenOptions): Promise<CommandOutput>;
+/**
+ * Compose the registry URL from a user-supplied base. Appends
+ * `/api/v1/registry` to whatever path is present, so
+ * `--server http://host/base` reaches `http://host/base/api/v1/registry`.
+ * If the supplied URL already ends with `/api/v1/registry` (with or
+ * without a trailing slash), the path is preserved as-is.
+ */
+export declare function composeRegistryUrl(serverUrl: string): URL;

package/dist/cli/codegen.js

@@ -0,0 +1,268 @@
+import { promises as fs } from "node:fs";
+import { basename, dirname } from "node:path";
+import { z } from "zod";
+import { ConnectionConfigurationError, resolveConnection } from "../connection.js";
+import {
+  REGISTRY_VERSION
+} from "../core/registry-snapshot.js";
+import { CodegenEmitError, emitRegistryDeclaration } from "./codegen-emit.js";
+const jsonSchema = z.union([z.boolean(), z.record(z.string(), z.unknown())]), workflowEntrySchema = z.object({
+  inputSchema: jsonSchema.optional(),
+  outputSchema: jsonSchema.optional(),
+  description: z.string().optional(),
+  tags: z.array(z.string()).optional()
+}).passthrough(), activityEntrySchema = z.object({
+  inputSchema: jsonSchema.optional(),
+  outputSchema: jsonSchema.optional(),
+  queue: z.string(),
+  description: z.string().optional()
+}).passthrough(), registrySnapshotSchema = z.object({
+  registryVersion: z.literal(REGISTRY_VERSION),
+  workflows: z.record(z.string(), workflowEntrySchema),
+  activities: z.record(z.string(), activityEntrySchema)
+}).passthrough();
+export async function executeCodegen(options) {
+  const snapshotResult = await loadSnapshot(options);
+  if (!snapshotResult.ok)
+    return formatFailure(snapshotResult.error, options);
+  const validation = validateSnapshot(snapshotResult.value);
+  if (!validation.ok)
+    return formatFailure(validation.error, options);
+  const snapshot = validation.value;
+  let content;
+  try {
+    content = emitRegistryDeclaration(snapshot);
+  } catch (error) {
+    if (error instanceof CodegenEmitError)
+      return formatFailure(`codegen: ${error.message}`, options);
+    const message = error instanceof Error ? error.message : String(error);
+    return formatFailure(`codegen: unexpected emitter failure: ${message}`, options);
+  }
+  const writeResult = await writeOutput(options.out, content);
+  if (!writeResult.ok)
+    return formatFailure(writeResult.error, options);
+  const workflowCount = Object.keys(snapshot.workflows).length, activityCount = Object.keys(snapshot.activities).length;
+  return formatSuccess(options, writeResult.action, workflowCount, activityCount);
+}
+function formatFailure(message, options) {
+  if (options.json)
+    return {
+      stdout: "",
+      stderr: JSON.stringify({ ok: !1, error: message }),
+      exitCode: 1
+    };
+  return { stdout: "", stderr: message, exitCode: 1 };
+}
+function formatSuccess(options, action, workflows, activities) {
+  if (options.json) {
+    const payload = { ok: !0, action, out: options.out, workflows, activities };
+    return { stdout: JSON.stringify(payload), exitCode: 0 };
+  }
+  if (action === "unchanged")
+    return { stdout: `codegen: ${options.out} is up to date`, exitCode: 0 };
+  return {
+    stdout: `codegen: wrote ${options.out} (${workflows} workflows, ${activities} activities)`,
+    exitCode: 0
+  };
+}
+async function loadSnapshot(options) {
+  if (options.from !== void 0 && options.server !== void 0)
+    return { ok: !1, error: "codegen: --server and --from cannot be used together" };
+  if (options.from !== void 0)
+    return loadSnapshotFromFile(options.from);
+  const connectionResult = resolveCodegenConnection(options);
+  if (!connectionResult.ok)
+    return connectionResult;
+  return loadSnapshotFromServer(connectionResult.value.baseUrl, connectionResult.value.token, options.timeoutMs);
+}
+function resolveCodegenConnection(options) {
+  try {
+    const connection = resolveConnection({
+      ...options.server !== void 0 ? { server: options.server } : {},
+      ...options.token !== void 0 ? { token: options.token } : {}
+    });
+    return {
+      ok: !0,
+      value: { baseUrl: connection.server.toString(), token: connection.token }
+    };
+  } catch (error) {
+    if (error instanceof ConnectionConfigurationError)
+      return { ok: !1, error: `codegen: ${error.message}` };
+    throw error;
+  }
+}
+async function loadSnapshotFromFile(path) {
+  const file = Bun.file(path);
+  if (!await file.exists())
+    return { ok: !1, error: `codegen: --from file not found at '${path}'` };
+  try {
+    return { ok: !0, value: await file.json() };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { ok: !1, error: `codegen: failed to parse JSON at '${path}': ${message}` };
+  }
+}
+export function composeRegistryUrl(serverUrl) {
+  const url = new URL(serverUrl), trimmedPath = url.pathname.replace(/\/+$/, "");
+  if (trimmedPath.endsWith("/api/v1/registry")) {
+    url.pathname = trimmedPath;
+    return url;
+  }
+  url.pathname = `${trimmedPath}/api/v1/registry`;
+  return url;
+}
+function buildRequestHeaders(token) {
+  const headers = new Headers({ Accept: "application/json" });
+  if (token !== void 0 && token !== "")
+    headers.set("Authorization", `Bearer ${token}`);
+  return headers;
+}
+function describeFetchError(error, timeoutMs, resolvedUrl) {
+  if (error instanceof DOMException && error.name === "TimeoutError")
+    return `codegen: timed out after ${timeoutMs}ms fetching ${resolvedUrl.toString()}`;
+  if (error instanceof DOMException && error.name === "AbortError")
+    return `codegen: request aborted after ${timeoutMs}ms fetching ${resolvedUrl.toString()}`;
+  const message = error instanceof Error ? error.message : String(error);
+  return `codegen: failed to fetch ${resolvedUrl.toString()}: ${message}`;
+}
+async function parseRegistryResponse(response, resolvedUrl) {
+  if (!response.ok)
+    return {
+      ok: !1,
+      error: `codegen: ${resolvedUrl.toString()} returned ${response.status} ${response.statusText}`
+    };
+  const contentType = response.headers.get("content-type") ?? "";
+  if (!/\bjson\b/i.test(contentType))
+    return {
+      ok: !1,
+      error: `codegen: ${resolvedUrl.toString()} returned non-JSON content-type '${contentType}'`
+    };
+  try {
+    return { ok: !0, value: await response.json() };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      ok: !1,
+      error: `codegen: failed to parse response body from ${resolvedUrl.toString()}: ${message}`
+    };
+  }
+}
+async function loadSnapshotFromServer(serverUrl, token, timeoutMs) {
+  let resolvedUrl;
+  try {
+    resolvedUrl = composeRegistryUrl(serverUrl);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { ok: !1, error: `codegen: invalid server URL '${serverUrl}': ${message}` };
+  }
+  let response;
+  try {
+    response = await fetch(resolvedUrl, {
+      headers: buildRequestHeaders(token),
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+  } catch (error) {
+    return { ok: !1, error: describeFetchError(error, timeoutMs, resolvedUrl) };
+  }
+  return parseRegistryResponse(response, resolvedUrl);
+}
+function validateSnapshot(value) {
+  if (value !== null && typeof value === "object" && "registryVersion" in value) {
+    const { registryVersion: actual } = value;
+    if (actual !== REGISTRY_VERSION)
+      return {
+        ok: !1,
+        error: `codegen: registryVersion ${String(actual)} is not supported (expected ${REGISTRY_VERSION}); upgrade or regenerate the snapshot`
+      };
+  }
+  const parsed = registrySnapshotSchema.safeParse(value);
+  if (!parsed.success)
+    return {
+      ok: !1,
+      error: `codegen: invalid registry snapshot: ${formatZodError(parsed.error)}`
+    };
+  return { ok: !0, value: {
+    registryVersion: parsed.data.registryVersion,
+    workflows: projectWorkflows(parsed.data.workflows),
+    activities: projectActivities(parsed.data.activities)
+  } };
+}
+function normalizeRootSchema(schema) {
+  if (schema === void 0)
+    return;
+  if (typeof schema === "boolean")
+    return {};
+  return schema;
+}
+function projectWorkflows(raw) {
+  const projected = Object.create(null);
+  for (const [name, entry] of Object.entries(raw)) {
+    const projection = {}, input = normalizeRootSchema(entry.inputSchema), output = normalizeRootSchema(entry.outputSchema);
+    if (input !== void 0)
+      projection.inputSchema = input;
+    if (output !== void 0)
+      projection.outputSchema = output;
+    if (entry.description !== void 0)
+      projection.description = entry.description;
+    if (entry.tags !== void 0)
+      projection.tags = entry.tags;
+    projected[name] = projection;
+  }
+  return projected;
+}
+function projectActivities(raw) {
+  const projected = Object.create(null);
+  for (const [name, entry] of Object.entries(raw)) {
+    const projection = { queue: entry.queue }, input = normalizeRootSchema(entry.inputSchema), output = normalizeRootSchema(entry.outputSchema);
+    if (input !== void 0)
+      projection.inputSchema = input;
+    if (output !== void 0)
+      projection.outputSchema = output;
+    if (entry.description !== void 0)
+      projection.description = entry.description;
+    projected[name] = projection;
+  }
+  return projected;
+}
+function formatZodError(error) {
+  return error.issues.map((issue) => {
+    return `${issue.path.length === 0 ? "<root>" : issue.path.join(".")}: ${issue.message}`;
+  }).join("; ");
+}
+async function writeOutput(outPath, content) {
+  const parent = dirname(outPath);
+  try {
+    if (!(await fs.stat(parent)).isDirectory())
+      return { ok: !1, error: `codegen: parent path '${parent}' is not a directory` };
+  } catch {
+    return { ok: !1, error: `codegen: parent directory '${parent}' does not exist` };
+  }
+  try {
+    if (await Bun.file(outPath).text() === content)
+      return { ok: !0, action: "unchanged" };
+  } catch {}
+  const tempPath = `${outPath}.codegen-${process.pid}-${randomSuffix()}.tmp`;
+  try {
+    await Bun.write(tempPath, content);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      ok: !1,
+      error: `codegen: failed to write temp file '${basename(tempPath)}' in '${dirname(outPath)}': ${message}`
+    };
+  }
+  try {
+    await fs.rename(tempPath, outPath);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    await fs.unlink(tempPath).catch(() => {});
+    return {
+      ok: !1,
+      error: `codegen: failed to rename '${basename(tempPath)}' to '${outPath}': ${message}`
+    };
+  }
+  return { ok: !0, action: "wrote" };
+}
+function randomSuffix() {
+  return Math.random().toString(16).slice(2, 14).padEnd(12, "0");
+}

package/dist/cli/command-suggestions.d.ts

@@ -0,0 +1,9 @@
+export declare function formatUnknownCommandError(command: string, knownSubcommands: readonly string[]): string;
+/**
+ * Returns the candidate with the smallest edit distance to `value`, or
+ * `undefined` when the nearest candidate's distance is strictly greater than
+ * `maxDistance`. A candidate at exactly `maxDistance` is accepted. Callers
+ * supply `maxDistance` so different suggestion surfaces can tune how forgiving
+ * their typo matching is. Internal to `src/cli/`; not part of the public API.
+ */
+export declare function findNearestCandidate(value: string, candidates: readonly string[], maxDistance: number): string | undefined;

package/dist/cli/command-suggestions.js

@@ -0,0 +1,27 @@
+export function formatUnknownCommandError(command, knownSubcommands) {
+  const suggestion = findNearestCandidate(command, knownSubcommands, 2);
+  return suggestion === void 0 ? `Unknown command '${command}'` : `Unknown command '${command}'. Did you mean '${suggestion}'?`;
+}
+export function findNearestCandidate(value, candidates, maxDistance) {
+  let nearest, nearestDistance = Number.POSITIVE_INFINITY;
+  for (const candidate of candidates) {
+    const distance = editDistance(value, candidate);
+    if (distance < nearestDistance) {
+      nearest = candidate;
+      nearestDistance = distance;
+    }
+  }
+  return nearestDistance <= maxDistance ? nearest : void 0;
+}
+function editDistance(left, right) {
+  const previous = Array.from({ length: right.length + 1 }, (_value, index) => index), current = Array.from({ length: right.length + 1 }, () => 0);
+  for (let leftIndex = 1;leftIndex <= left.length; leftIndex++) {
+    current[0] = leftIndex;
+    for (let rightIndex = 1;rightIndex <= right.length; rightIndex++) {
+      const substitutionCost = left[leftIndex - 1] === right[rightIndex - 1] ? 0 : 1;
+      current[rightIndex] = Math.min(previous[rightIndex] + 1, current[rightIndex - 1] + 1, previous[rightIndex - 1] + substitutionCost);
+    }
+    previous.splice(0, previous.length, ...current);
+  }
+  return previous[right.length];
+}

package/dist/cli/completions.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `weft completions generate|install --shell zsh|bash|fish` — emit or install a
+ * shell completion script for the `weft` CLI.
+ *
+ * `generate` prints the script to stdout (pipe it into your shell config).
+ * `install` writes it to the conventional per-shell completion directory and
+ * prints the path plus any one-time activation step.
+ *
+ * @module cli/completions
+ */
+import type { CommandOutput, CompletionShell, CompletionsCommand } from './types.ts';
+/** Generate the completion script for the requested shell. */
+export declare function generateCompletionScript(shell: CompletionShell): string;
+/** Conventional install path for each shell's completion script. */
+export declare function completionInstallPath(shell: CompletionShell): string;
+/** Execute `weft completions generate|install`. */
+export declare function executeCompletions(command: CompletionsCommand): Promise<CommandOutput>;

package/dist/cli/completions.js

@@ -0,0 +1,112 @@
+import { mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+function homeDirectory() {
+  return Bun.env.HOME ?? homedir();
+}
+const TOP_LEVEL_COMMANDS = [
+  "serve",
+  "doctor",
+  "conformance",
+  "schedule",
+  "timeline",
+  "version:check",
+  "validate",
+  "codegen",
+  "api",
+  "server",
+  "workflow",
+  "tail",
+  "completions",
+  "version"
+], SUBCOMMANDS = {
+  server: ["health", "info"],
+  workflow: ["ls", "get", "events", "start", "cancel", "signal"],
+  schedule: ["list", "create", "pause", "resume", "cancel"],
+  completions: ["generate", "install"]
+};
+export function generateCompletionScript(shell) {
+  if (shell === "zsh")
+    return zshScript();
+  if (shell === "bash")
+    return bashScript();
+  return fishScript();
+}
+function zshScript() {
+  const commands = TOP_LEVEL_COMMANDS.join(" "), subcases = Object.entries(SUBCOMMANDS).map(([noun, subs]) => `        ${noun}) _values 'subcommand' ${subs.join(" ")} ;;`).join(`
+`);
+  return `#compdef weft
+_weft() {
+  local -a commands
+  commands=(${commands})
+  if (( CURRENT == 2 )); then
+    _values 'command' \${commands[@]}
+    return
+  fi
+  case "\${words[2]}" in
+${subcases}
+  esac
+}
+_weft "$@"
+`;
+}
+function bashScript() {
+  const commands = TOP_LEVEL_COMMANDS.join(" "), subcases = Object.entries(SUBCOMMANDS).map(([noun, subs]) => `      ${noun}) COMPREPLY=( $(compgen -W "${subs.join(" ")}" -- "$cur") ) ;;`).join(`
+`);
+  return `# bash completion for weft
+_weft_completions() {
+  local cur prev
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  if [ "$COMP_CWORD" -eq 1 ]; then
+    COMPREPLY=( $(compgen -W "${commands}" -- "$cur") )
+    return
+  fi
+  case "\${COMP_WORDS[1]}" in
+${subcases}
+  esac
+}
+complete -F _weft_completions weft
+`;
+}
+function fishScript() {
+  const topLevel = TOP_LEVEL_COMMANDS.map((command) => `complete -c weft -n '__fish_use_subcommand' -a '${command}'`).join(`
+`), nested = Object.entries(SUBCOMMANDS).flatMap(([noun, subs]) => subs.map((sub) => `complete -c weft -n '__fish_seen_subcommand_from ${noun}' -a '${sub}'`)).join(`
+`);
+  return `# fish completion for weft
+${topLevel}
+${nested}
+`;
+}
+export function completionInstallPath(shell) {
+  const home = homeDirectory();
+  if (shell === "zsh")
+    return join(home, ".zsh", "completions", "_weft");
+  if (shell === "bash")
+    return join(home, ".bash_completion.d", "weft");
+  return join(home, ".config", "fish", "completions", "weft.fish");
+}
+function activationHint(shell, path) {
+  if (shell === "zsh")
+    return "Add 'fpath=(~/.zsh/completions $fpath)' and 'autoload -U compinit && compinit' to ~/.zshrc, then restart your shell.";
+  if (shell === "bash")
+    return `Add 'source ${path}' to ~/.bashrc, then restart your shell.`;
+  return "Fish loads completions from this directory automatically; restart your shell.";
+}
+export async function executeCompletions(command) {
+  const script = generateCompletionScript(command.shell);
+  if (command.action === "generate")
+    return { stdout: script, exitCode: 0 };
+  const path = completionInstallPath(command.shell);
+  try {
+    await mkdir(join(path, ".."), { recursive: !0 });
+    await Bun.write(path, script);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { stdout: "", stderr: `completions: failed to write ${path}: ${message}`, exitCode: 1 };
+  }
+  return {
+    stdout: `Installed ${command.shell} completions to ${path}
+${activationHint(command.shell, path)}`,
+    exitCode: 0
+  };
+}

package/dist/cli/conformance.d.ts

@@ -0,0 +1,9 @@
+import type { CommandOutput } from './types.ts';
+type ConformanceCommandOptions = {
+    timeoutMs: number;
+    json: boolean;
+    workerCommand: string[];
+};
+/** Runs RemoteWorker protocol conformance checks against a candidate worker command. */
+export declare function executeConformance(options: ConformanceCommandOptions): Promise<CommandOutput>;
+export {};