@united-workforce/cli 0.1.0

package/src/commands/config.ts

@@ -0,0 +1,304 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse, stringify } from "yaml";
+
+/**
+ * Valid configuration key schema
+ */
+const VALID_CONFIG_KEYS: Record<
+  string,
+  { nested: boolean; knownFields?: string[]; minDepth?: number }
+> = {
+  providers: {
+    nested: true,
+    knownFields: ["baseUrl", "apiKey"],
+  },
+  models: {
+    nested: true,
+    knownFields: ["provider", "name"],
+  },
+  agents: {
+    nested: true,
+    knownFields: ["command", "args"],
+  },
+  agentOverrides: {
+    nested: true,
+    // agentOverrides.<workflowName>.<roleName> = agentAlias (string value)
+    // No knownFields — workflow/role names are user-defined
+  },
+  modelOverrides: {
+    nested: true,
+    minDepth: 2,
+    // modelOverrides.<scenario> = modelAlias (string value)
+    // No knownFields — scenarios are user-defined
+  },
+  defaultAgent: { nested: false },
+  defaultModel: { nested: false },
+};
+
+/**
+ * Validate a config key path against the known schema
+ */
+function validateConfigKey(path: string[]): void {
+  if (path.length === 0) {
+    throw new Error("Path cannot be empty");
+  }
+
+  const topLevel = path[0];
+  const schema = VALID_CONFIG_KEYS[topLevel];
+
+  if (!schema) {
+    const validKeys = Object.keys(VALID_CONFIG_KEYS).join(", ");
+    throw new Error(`Unknown config key: ${topLevel}. Valid top-level keys are: ${validKeys}`);
+  }
+
+  // Scalar keys cannot have nested paths
+  if (!schema.nested && path.length > 1) {
+    throw new Error(`${topLevel} is a scalar key and cannot have nested properties`);
+  }
+
+  // Nested keys must have at least minDepth segments (default 3)
+  const minDepth = schema.minDepth ?? 3;
+  if (schema.nested && path.length < minDepth) {
+    const fields = schema.knownFields?.join(", ") ?? "";
+    throw new Error(
+      `Incomplete path for ${topLevel}. Must specify a field (e.g., ${topLevel}.<name>.<field>). Valid fields: ${fields}`,
+    );
+  }
+
+  // Validate the field name for nested keys
+  if (schema.nested && path.length >= 3 && schema.knownFields) {
+    const field = path[path.length - 1];
+    if (!schema.knownFields.includes(field)) {
+      throw new Error(
+        `Unknown field '${field}' in ${topLevel}. Valid fields are: ${schema.knownFields.join(", ")}`,
+      );
+    }
+  }
+}
+
+/**
+ * Returns the path to the config.yaml file
+ */
+export function getConfigPath(storageRoot: string): string {
+  return join(storageRoot, "config.yaml");
+}
+
+/**
+ * Load and parse YAML config file
+ */
+export function loadConfig(configPath: string): Record<string, unknown> {
+  if (!existsSync(configPath)) {
+    throw new Error(`Config file not found: ${configPath}`);
+  }
+  const content = readFileSync(configPath, "utf8");
+  if (!content.trim()) {
+    return {};
+  }
+  try {
+    const parsed = parse(content);
+    return (parsed ?? {}) as Record<string, unknown>;
+  } catch (error) {
+    throw new Error(
+      `Invalid YAML in config file: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}
+
+/**
+ * Save config as YAML
+ */
+export function saveConfig(configPath: string, config: Record<string, unknown>): void {
+  const dir = join(configPath, "..");
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  const yaml = stringify(config);
+  writeFileSync(configPath, yaml, "utf8");
+}
+
+/**
+ * Parse dot-notation key into path segments
+ */
+export function parseDotPath(key: string): string[] {
+  return key.split(".");
+}
+
+/**
+ * Get nested value from object using path array
+ */
+export function getNestedValue(obj: Record<string, unknown>, path: string[]): unknown {
+  let current: unknown = obj;
+  for (const segment of path) {
+    if (current === null || current === undefined || typeof current !== "object") {
+      return undefined;
+    }
+    current = (current as Record<string, unknown>)[segment];
+  }
+  return current;
+}
+
+/**
+ * Set nested value in object using path array (mutates obj)
+ */
+export function setNestedValue(obj: Record<string, unknown>, path: string[], value: unknown): void {
+  if (path.length === 0) {
+    throw new Error("Path cannot be empty");
+  }
+
+  let current: Record<string, unknown> = obj;
+
+  // Navigate/create to the parent of the target
+  for (let i = 0; i < path.length - 1; i++) {
+    const segment = path[i];
+    const next = current[segment];
+
+    if (next === null || next === undefined) {
+      // Create intermediate object
+      const newObj: Record<string, unknown> = {};
+      current[segment] = newObj;
+      current = newObj;
+    } else if (typeof next === "object" && !Array.isArray(next)) {
+      // Navigate into existing object
+      current = next as Record<string, unknown>;
+    } else {
+      // Cannot navigate into non-object
+      throw new Error(
+        `Cannot set property '${path[i + 1]}' on non-object at path '${path.slice(0, i + 1).join(".")}'`,
+      );
+    }
+  }
+
+  // Set the final value
+  const lastSegment = path[path.length - 1];
+  current[lastSegment] = value;
+}
+
+/**
+ * Deep clone and mask all apiKey values in providers section
+ */
+export function maskApiKeys(config: Record<string, unknown>): Record<string, unknown> {
+  // Deep clone
+  const cloned = JSON.parse(JSON.stringify(config)) as Record<string, unknown>;
+
+  // Mask apiKey values in providers
+  if (cloned.providers && typeof cloned.providers === "object") {
+    const providers = cloned.providers as Record<string, unknown>;
+    for (const providerName of Object.keys(providers)) {
+      const provider = providers[providerName];
+      if (provider && typeof provider === "object") {
+        const providerObj = provider as Record<string, unknown>;
+        if ("apiKey" in providerObj) {
+          providerObj.apiKey = "***MASKED***";
+        }
+      }
+    }
+  }
+
+  return cloned;
+}
+
+/**
+ * List all configuration values (masks API keys)
+ */
+export async function cmdConfigList(storageRoot: string): Promise<unknown> {
+  const configPath = getConfigPath(storageRoot);
+  const config = loadConfig(configPath);
+  const masked = maskApiKeys(config);
+  return masked;
+}
+
+/**
+ * Get a specific configuration value
+ */
+export async function cmdConfigGet(storageRoot: string, key: string): Promise<unknown> {
+  const configPath = getConfigPath(storageRoot);
+  const config = loadConfig(configPath);
+  const path = parseDotPath(key);
+  const value = getNestedValue(config, path);
+
+  if (value === undefined) {
+    throw new Error(`Key not found: ${key}`);
+  }
+
+  return value;
+}
+
+/**
+ * Parse value for args key (must be JSON array)
+ */
+function parseArgsValue(value: string): unknown {
+  if (value.startsWith("[")) {
+    try {
+      const parsed = JSON.parse(value);
+      if (!Array.isArray(parsed)) {
+        throw new Error("Value must be an array");
+      }
+      return parsed;
+    } catch (error) {
+      throw new Error(
+        `Invalid JSON array for args key: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+  throw new Error("Value for 'args' key must be a JSON array starting with '['");
+}
+
+/**
+ * Validate that we're not setting a property on a non-object
+ */
+function validateParentPath(
+  config: Record<string, unknown>,
+  path: string[],
+  lastSegment: string,
+): void {
+  if (path.length > 1) {
+    const parentPath = path.slice(0, -1);
+    const parent = getNestedValue(config, parentPath);
+    if (parent !== null && parent !== undefined && typeof parent !== "object") {
+      throw new Error(
+        `Cannot set property '${lastSegment}' on non-object at path '${parentPath.join(".")}'`,
+      );
+    }
+  }
+}
+
+/**
+ * Set a specific configuration value
+ */
+export async function cmdConfigSet(
+  storageRoot: string,
+  key: string,
+  value: string,
+): Promise<unknown> {
+  const configPath = getConfigPath(storageRoot);
+
+  // Load existing config or create empty one
+  let config: Record<string, unknown>;
+  if (existsSync(configPath)) {
+    config = loadConfig(configPath);
+  } else {
+    config = {};
+  }
+
+  const path = parseDotPath(key);
+
+  // Validate the key path
+  validateConfigKey(path);
+
+  const lastSegment = path[path.length - 1];
+
+  // Parse value if it's for an array key (args)
+  let parsedValue: unknown = value;
+  if (lastSegment === "args") {
+    parsedValue = parseArgsValue(value);
+  }
+
+  // Validate we're not setting a property on a non-object
+  validateParentPath(config, path, lastSegment);
+
+  setNestedValue(config, path, parsedValue);
+  saveConfig(configPath, config);
+
+  return { key, value: parsedValue };
+}

package/src/commands/log.ts

@@ -0,0 +1,116 @@
+import { readdir, readFile, stat, unlink } from "node:fs/promises";
+import { join } from "node:path";
+
+type LogListItem = {
+  name: string;
+  size: number;
+  date: string;
+};
+
+type LogShowFilter = {
+  thread: string | null;
+  process: string | null;
+  date: string | null;
+};
+
+type LogEntry = {
+  ts: string;
+  pid: string;
+  tag: string;
+  msg: string;
+  thread: string | null;
+  workflow: string | null;
+};
+
+type LogCleanResult = {
+  deleted: number;
+};
+
+function logsDir(storageRoot: string): string {
+  return join(storageRoot, "logs");
+}
+
+async function listLogFiles(dir: string): Promise<Array<string>> {
+  try {
+    const files = await readdir(dir);
+    return files.filter((f) => f.endsWith(".jsonl")).sort();
+  } catch {
+    return [];
+  }
+}
+
+function dateFromFilename(name: string): string {
+  return name.replace(".jsonl", "");
+}
+
+async function parseJsonlFile(path: string): Promise<Array<LogEntry>> {
+  const content = await readFile(path, "utf-8");
+  const lines = content
+    .trim()
+    .split("\n")
+    .filter((l) => l.length > 0);
+  return lines.map((line) => JSON.parse(line) as LogEntry);
+}
+
+export async function cmdLogList(storageRoot: string): Promise<Array<LogListItem>> {
+  const dir = logsDir(storageRoot);
+  const files = await listLogFiles(dir);
+  const items: Array<LogListItem> = [];
+  for (const name of files) {
+    const s = await stat(join(dir, name));
+    items.push({ name, size: s.size, date: dateFromFilename(name) });
+  }
+  // sort by date descending
+  items.sort((a, b) => (a.date > b.date ? -1 : a.date < b.date ? 1 : 0));
+  return items;
+}
+
+export async function cmdLogShow(
+  storageRoot: string,
+  filter: LogShowFilter,
+): Promise<Array<LogEntry>> {
+  const dir = logsDir(storageRoot);
+  let files: Array<string>;
+
+  if (filter.date !== null) {
+    files = [`${filter.date}.jsonl`];
+  } else {
+    files = await listLogFiles(dir);
+  }
+
+  let entries: Array<LogEntry> = [];
+  for (const file of files) {
+    try {
+      const parsed = await parseJsonlFile(join(dir, file));
+      entries = entries.concat(parsed);
+    } catch {
+      // file doesn't exist or is unreadable, skip
+    }
+  }
+
+  if (filter.thread !== null) {
+    entries = entries.filter((e) => e.thread === filter.thread);
+  }
+  if (filter.process !== null) {
+    entries = entries.filter((e) => e.pid === filter.process);
+  }
+
+  entries.sort((a, b) => (a.ts < b.ts ? -1 : a.ts > b.ts ? 1 : 0));
+  return entries;
+}
+
+export async function cmdLogClean(storageRoot: string, before: string): Promise<LogCleanResult> {
+  const dir = logsDir(storageRoot);
+  const files = await listLogFiles(dir);
+  let deleted = 0;
+
+  for (const name of files) {
+    const date = dateFromFilename(name);
+    if (date < before) {
+      await unlink(join(dir, name));
+      deleted++;
+    }
+  }
+
+  return { deleted };
+}

package/src/commands/prompt.ts

@@ -0,0 +1,81 @@
+import {
+  generateAdapterDevelopingReference,
+  generateBootstrapReference,
+  generateUsageReference,
+  generateWorkflowAuthoringReference,
+} from "@united-workforce/util";
+
+export {
+  generateAdapterDevelopingReference as cmdPromptAdapterDeveloping,
+  generateBootstrapReference as cmdPromptBootstrap,
+  generateUsageReference as cmdPromptUsageReference,
+  generateWorkflowAuthoringReference as cmdPromptWorkflowAuthoring,
+};
+
+const PROMPT_ENTRIES: ReadonlyArray<{ name: string; generate: () => string }> = [
+  { name: "usage", generate: generateUsageReference },
+  { name: "workflow-authoring", generate: generateWorkflowAuthoringReference },
+  { name: "adapter-developing", generate: generateAdapterDevelopingReference },
+  { name: "bootstrap", generate: generateBootstrapReference },
+];
+
+export function cmdPromptList(): ReadonlyArray<string> {
+  return PROMPT_ENTRIES.map((e) => e.name);
+}
+
+export function cmdPromptUsage(): string {
+  return PROMPT_ENTRIES.filter((e) => e.name !== "bootstrap")
+    .map((e) => e.generate())
+    .join("\n\n---\n\n");
+}
+
+export function cmdPromptSetup(): string {
+  return `# uwf Skill Setup
+
+You are being asked to install or update the uwf (United Workforce) skill
+so that you know how to use the \`uwf\` CLI for workflow orchestration.
+
+## Steps
+
+1. **Check if uwf CLI is installed:**
+   \`\`\`bash
+   uwf --help
+   \`\`\`
+   If not installed: \`npm install -g @united-workforce/cli\`
+
+2. **Clean up old versions of the skill** (if any exist):
+   - Look for any existing uwf/workflow skill files in your skill directories
+     (e.g. \`~/.hermes/skills/uwf/SKILL.md\` or similar paths).
+   - If a skill exists, read its \`version\` from the YAML frontmatter.
+   - If the version matches the current CLI version (\`uwf --version\`), you're done — no update needed.
+   - If the version is older, **delete the old skill file** before proceeding.
+
+3. **Install the bootstrap skill:**
+   \`\`\`bash
+   uwf prompt bootstrap > ~/.hermes/skills/uwf/SKILL.md
+   \`\`\`
+   The bootstrap prompt already includes complete YAML frontmatter — no editing needed.
+
+4. **Verify** the skill is loadable by your agent framework.
+
+## Individual prompts
+
+Each prompt outputs a complete SKILL.md with frontmatter — pipe directly to a file:
+
+\`\`\`bash
+uwf prompt list                                              # list available prompt names
+uwf prompt usage > ~/.hermes/skills/uwf-usage/SKILL.md      # CLI usage guide
+uwf prompt workflow-authoring > ~/.hermes/skills/uwf-workflow-authoring/SKILL.md
+uwf prompt adapter-developing > ~/.hermes/skills/uwf-adapter-developing/SKILL.md
+uwf prompt bootstrap > ~/.hermes/skills/uwf/SKILL.md        # bootstrap skill
+\`\`\`
+
+## Notes
+
+- The skill content is bundled with the CLI and versioned with it — always use
+  \`uwf prompt usage\` to get the content matching your installed version.
+- Do NOT hand-edit the skill body. If the CLI is updated, re-run \`uwf prompt setup\`
+  and follow the steps again.
+- When upgrading, always delete the old skill first to avoid stale instructions.
+`;
+}