facult 2.10.0 → 2.12.0

package/src/remote.ts

@@ -9,8 +9,9 @@ import {
   relative,
   resolve,
 } from "node:path";
-import { fileURLToPath } from "node:url";
 import { isCancel, multiselect, select, text } from "@clack/prompts";
+import { facultBuiltinPackRoot } from "./builtin";
+import { parseCliContextArgs, resolveCliContextRoot } from "./cli-context";
 import {
   renderBullets,
   renderCatalog,
@@ -42,6 +43,7 @@ import {
   type RemoteAgentItem,
   type RemoteIndexItem,
   type RemoteIndexManifest,
+  type RemoteInstructionItem,
   type RemoteItemType,
   type RemoteMcpItem,
   type RemoteSkillItem,
@@ -59,6 +61,8 @@ const QUERY_SPLIT_RE = /\s+/;
 const MD_EXT_RE = /\.md$/i;
 const FILE_EXT_RE = /\.[A-Za-z0-9]+$/;
 const TRAILING_SLASH_RE = /\/+$/;
+const LEADING_SLASH_RE = /^\/+/;
+const INSTRUCTION_TITLE_SPLIT_RE = /[-_.\s]+/;
 const PROMPT_PATH_SPLIT_RE = /[,\n]/;
 const GIT_WORKTREE_LINE_RE = /\r?\n/;
 
@@ -221,6 +225,52 @@ Use this skill when the task repeatedly follows a known workflow and you want co
         },
       },
     },
+    {
+      id: "instruction-template",
+      type: "instruction",
+      title: "Instruction Template",
+      description:
+        "Reusable markdown instruction scaffold with ref and snippet composition examples.",
+      version: "1.0.0",
+      tags: ["template", "dx", "instruction"],
+      instruction: {
+        name: "WORKFLOW.md",
+        content: `---
+description: "{{name}} reusable instruction"
+tags: [instruction, workflow]
+---
+
+# {{title}}
+
+Use this instruction when the task needs repeatable guidance that should be discoverable, targetable by writeback, and composable into agent docs.
+
+## Scope
+
+- Applies to:
+- Does not apply to:
+- Project-specific overrides:
+
+## Guidance
+
+- Keep the rule concrete enough that another agent can follow it without chat context.
+- Link deeper reusable guidance with canonical refs such as \`@ai/instructions/VERIFICATION.md\` or \`@project/instructions/TESTING.md\`.
+- Reuse stable partials with snippet markers when the same block appears in more than one rendered doc.
+
+## Composition
+
+<!-- fclty:global/team/example -->
+<!-- /fclty:global/team/example -->
+
+## Writeback Targeting
+
+Record durable friction against this instruction with:
+
+\`\`\`bash
+fclt ai writeback add --kind missing_context --summary "<what was missing>" --asset instruction:{{assetName}}
+\`\`\`
+`,
+      },
+    },
     {
       id: "mcp-stdio-template",
       type: "mcp",
@@ -1221,11 +1271,6 @@ updated_at = ${timestamp}
   };
 }
 
-function builtinPackRoot(packName: string): string {
-  const here = dirname(fileURLToPath(import.meta.url));
-  return join(here, "..", "assets", "packs", packName);
-}
-
 async function pathExists(pathValue: string): Promise<boolean> {
   try {
     await Bun.file(pathValue).stat();
@@ -1258,15 +1303,15 @@ async function listFilesRecursive(rootDir: string): Promise<string[]> {
   return out.sort();
 }
 
-async function scaffoldBuiltinProjectAiPack(args: {
-  cwd?: string;
+async function scaffoldBuiltinOperatingModelPack(args: {
+  rootDir: string;
   homeDir?: string;
   dryRun?: boolean;
   force?: boolean;
+  installedAs?: string;
 }): Promise<InstallResult> {
-  const cwd = resolve(args.cwd ?? process.cwd());
-  const rootDir = join(cwd, ".ai");
-  const packRoot = builtinPackRoot("facult-operating-model");
+  const rootDir = resolve(args.rootDir);
+  const packRoot = facultBuiltinPackRoot("facult-operating-model");
   const files = await listFilesRecursive(packRoot);
   const changedPaths: string[] = [];
 
@@ -1307,7 +1352,7 @@ async function scaffoldBuiltinProjectAiPack(args: {
   return {
     ref: `${BUILTIN_INDEX_NAME}:facult-operating-model`,
     type: "skill",
-    installedAs: "project-ai",
+    installedAs: args.installedAs ?? "operating-model",
     path: rootDir,
     sourceTrustLevel: "trusted",
     dryRun: Boolean(args.dryRun),
@@ -1315,6 +1360,22 @@ async function scaffoldBuiltinProjectAiPack(args: {
   };
 }
 
+async function scaffoldBuiltinProjectAiPack(args: {
+  cwd?: string;
+  homeDir?: string;
+  dryRun?: boolean;
+  force?: boolean;
+}): Promise<InstallResult> {
+  const cwd = resolve(args.cwd ?? process.cwd());
+  return await scaffoldBuiltinOperatingModelPack({
+    rootDir: join(cwd, ".ai"),
+    homeDir: args.homeDir,
+    dryRun: args.dryRun,
+    force: args.force,
+    installedAs: "project-ai",
+  });
+}
+
 function compareVersions(a: string, b: string): number {
   const aTokens = (a.match(VERSION_TOKEN_RE) ?? []).map((t) => t.toLowerCase());
   const bTokens = (b.match(VERSION_TOKEN_RE) ?? []).map((t) => t.toLowerCase());
@@ -1449,7 +1510,8 @@ function parseIndexItem(raw: unknown): RemoteIndexItem | null {
     type !== "skill" &&
     type !== "mcp" &&
     type !== "agent" &&
-    type !== "snippet"
+    type !== "snippet" &&
+    type !== "instruction"
   ) {
     return null;
   }
@@ -1548,6 +1610,30 @@ function parseIndexItem(raw: unknown): RemoteIndexItem | null {
     };
   }
 
+  if (type === "instruction") {
+    const instructionRaw = obj.instruction;
+    if (!isPlainObject(instructionRaw)) {
+      return null;
+    }
+    const name =
+      typeof instructionRaw.name === "string" ? instructionRaw.name.trim() : "";
+    const content =
+      typeof instructionRaw.content === "string" ? instructionRaw.content : "";
+    if (!(name && content)) {
+      return null;
+    }
+    return {
+      id,
+      type,
+      title,
+      description,
+      version,
+      sourceUrl,
+      tags,
+      instruction: { name, content },
+    };
+  }
+
   const snippetRaw = obj.snippet;
   if (!isPlainObject(snippetRaw)) {
     return null;
@@ -1719,7 +1805,8 @@ async function loadInstalledState(
         type !== "skill" &&
         type !== "mcp" &&
         type !== "agent" &&
-        type !== "snippet"
+        type !== "snippet" &&
+        type !== "instruction"
       ) {
         continue;
       }
@@ -2023,6 +2110,69 @@ async function installSnippetItem(args: {
   };
 }
 
+function normalizeInstructionName(value: string): string {
+  const normalized = value
+    .trim()
+    .replaceAll("\\", "/")
+    .replace(LEADING_SLASH_RE, "");
+  if (!normalized) {
+    throw new Error("Instruction name is required");
+  }
+  const withExt = MD_EXT_RE.test(normalized) ? normalized : `${normalized}.md`;
+  if (!isSafeRelativePath(withExt)) {
+    throw new Error(`Invalid instruction name: ${value}`);
+  }
+  return withExt;
+}
+
+function instructionTitleFromFileName(fileName: string): string {
+  const base = basename(fileName).replace(MD_EXT_RE, "");
+  return base
+    .split(INSTRUCTION_TITLE_SPLIT_RE)
+    .filter(Boolean)
+    .map((part) => `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`)
+    .join(" ");
+}
+
+function instructionAssetName(fileName: string): string {
+  return basename(fileName).replace(MD_EXT_RE, "");
+}
+
+async function installInstructionItem(args: {
+  item: RemoteInstructionItem;
+  installAs?: string;
+  rootDir: string;
+  force: boolean;
+  dryRun: boolean;
+}): Promise<{ installedAs: string; path: string; changedPaths: string[] }> {
+  const fileName = normalizeInstructionName(
+    args.installAs ?? args.item.instruction.name
+  );
+  const instructionPath = join(args.rootDir, "instructions", fileName);
+  assertInstallPath(instructionPath, join(args.rootDir, "instructions"));
+  if ((await fileExists(instructionPath)) && !args.force) {
+    throw new Error(
+      `Instruction already exists: ${fileName} (use --force to overwrite)`
+    );
+  }
+  if (!args.dryRun) {
+    await mkdir(dirname(instructionPath), { recursive: true });
+    await Bun.write(
+      instructionPath,
+      renderTemplate(args.item.instruction.content, {
+        name: fileName,
+        title: instructionTitleFromFileName(fileName),
+        assetName: instructionAssetName(fileName),
+      })
+    );
+  }
+  return {
+    installedAs: fileName,
+    path: instructionPath,
+    changedPaths: [instructionPath],
+  };
+}
+
 async function installParsedItem(args: {
   parsedRef: { index: string; itemId: string };
   item: RemoteIndexItem;
@@ -2064,7 +2214,7 @@ async function installParsedItem(args: {
       force: args.force,
       dryRun: args.dryRun,
     });
-  } else {
+  } else if (args.item.type === "snippet") {
     writeResult = await installSnippetItem({
       item: args.item,
       installAs: args.installAs,
@@ -2072,6 +2222,14 @@ async function installParsedItem(args: {
       force: args.force,
       dryRun: args.dryRun,
     });
+  } else {
+    writeResult = await installInstructionItem({
+      item: args.item,
+      installAs: args.installAs,
+      rootDir: args.rootDir,
+      force: args.force,
+      dryRun: args.dryRun,
+    });
   }
 
   const result: InstallResult = {
@@ -2654,10 +2812,16 @@ function printTemplatesHelp() {
             renderCode(
               "fclt templates init agent <name> [--force] [--dry-run]"
             ),
+            renderCode(
+              "fclt templates init instruction <name> [--force] [--dry-run]"
+            ),
             renderCode(
               "fclt templates init snippet <marker> [--force] [--dry-run]"
             ),
             renderCode("fclt templates init agents [--force] [--dry-run]"),
+            renderCode(
+              "fclt templates init operating-model [--global|--project|--root PATH] [--force] [--dry-run]"
+            ),
             renderCode("fclt templates init project-ai [--force] [--dry-run]"),
             renderCode(
               "fclt templates init automation <template-id> [--scope global|project|wide] [--name <name>] [--project-root <path>] [--cwds <path1,path2>] [--rrule <RRULE>] [--status PAUSED|ACTIVE] [--yes] [--dry-run]"
@@ -2719,6 +2883,53 @@ function parseLongFlag(argv: string[], flag: string): string | null {
   return null;
 }
 
+const TEMPLATE_INIT_VALUE_FLAGS = new Set([
+  "--automation-status",
+  "--cwds",
+  "--name",
+  "--project-root",
+  "--root",
+  "--rrule",
+  "--scope",
+  "--status",
+]);
+
+function parseTemplateInitArgs(argv: string[]): {
+  positional: string[];
+  rootArg?: string;
+} {
+  const positional: string[] = [];
+  let rootArg: string | undefined;
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (!arg) {
+      continue;
+    }
+    if (arg === "--root") {
+      rootArg = argv[i + 1] ?? undefined;
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith("--root=")) {
+      rootArg = arg.slice("--root=".length);
+      continue;
+    }
+    if (TEMPLATE_INIT_VALUE_FLAGS.has(arg)) {
+      i += 1;
+      continue;
+    }
+    const equalFlag = arg.startsWith("--") ? arg.split("=", 1)[0] : "";
+    if (equalFlag && TEMPLATE_INIT_VALUE_FLAGS.has(equalFlag)) {
+      continue;
+    }
+    if (arg.startsWith("-")) {
+      continue;
+    }
+    positional.push(arg);
+  }
+  return { positional, rootArg };
+}
+
 export async function sourcesCommand(
   argv: string[],
   ctx: RemoteCommandContext = {}
@@ -3052,6 +3263,14 @@ export async function templatesCommand(
         description: item.description ?? "",
         version: item.version ?? "",
       })),
+      {
+        id: "operating-model",
+        type: "pack",
+        title: "Operating Model Pack",
+        description:
+          "Install the built-in Facult operating-model pack into the active canonical root.",
+        version: "1.0.0",
+      },
       {
         id: "project-ai",
         type: "pack",
@@ -3101,7 +3320,7 @@ export async function templatesCommand(
   const [kind, ...args] = rest;
   if (!kind) {
     console.error(
-      "templates init requires a kind (skill|mcp|agent|snippet|agents|claude|project-ai|automation)"
+      "templates init requires a kind (skill|mcp|agent|instruction|snippet|agents|claude|operating-model|project-ai|automation)"
     );
     process.exitCode = 2;
     return;
@@ -3109,7 +3328,8 @@ export async function templatesCommand(
   const dryRun = args.includes("--dry-run");
   const force = args.includes("--force");
   const json = args.includes("--json");
-  const positional = args.filter((a) => a && !a.startsWith("-"));
+  const parsedArgs = parseTemplateInitArgs(args);
+  const positional = parsedArgs.positional;
 
   if (kind === "project-ai") {
     try {
@@ -3144,6 +3364,51 @@ export async function templatesCommand(
     }
   }
 
+  if (kind === "operating-model") {
+    try {
+      const context = parseCliContextArgs(args, { allowScope: false });
+      const cwd = resolve(ctx.cwd ?? process.cwd());
+      const rootDir = ctx.rootDir
+        ? resolve(ctx.rootDir)
+        : context.scope === "project" && !context.rootArg
+          ? join(findGitRootFromPath(cwd) ?? cwd, ".ai")
+          : resolveCliContextRoot({
+              rootArg: context.rootArg,
+              scope: context.scope,
+              homeDir: ctx.homeDir,
+              cwd,
+            });
+      const result = await scaffoldBuiltinOperatingModelPack({
+        rootDir,
+        homeDir: ctx.homeDir,
+        dryRun,
+        force,
+      });
+      if (json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+      }
+      const action = dryRun ? "Would install" : "Installed";
+      console.log(
+        renderPage({
+          title: `fclt templates init ${kind}`,
+          subtitle: `${action} ${result.installedAs} into ${result.path}`,
+          sections: [
+            {
+              title: "Changed Paths",
+              lines: renderBullets(result.changedPaths),
+            },
+          ],
+        })
+      );
+      return;
+    } catch (err) {
+      console.error(err instanceof Error ? err.message : String(err));
+      process.exitCode = 1;
+      return;
+    }
+  }
+
   let ref = "";
   let as: string | undefined;
   if (kind === "skill") {
@@ -3176,6 +3441,14 @@ export async function templatesCommand(
     as = normalizedName.endsWith(".toml")
       ? normalizedName
       : `${normalizedName}/agent.toml`;
+  } else if (kind === "instruction") {
+    ref = `${BUILTIN_INDEX_NAME}:instruction-template`;
+    as = positional[0];
+    if (!as) {
+      console.error("templates init instruction requires a <name>");
+      process.exitCode = 2;
+      return;
+    }
   } else if (kind === "snippet") {
     ref = `${BUILTIN_INDEX_NAME}:snippet-template`;
     as = positional[0];
@@ -3285,7 +3558,7 @@ export async function templatesCommand(
       dryRun,
       force,
       homeDir: ctx.homeDir,
-      rootDir: ctx.rootDir,
+      rootDir: parsedArgs.rootArg ?? ctx.rootDir,
       cwd: ctx.cwd,
       fetchJson: ctx.fetchJson,
       fetchText: ctx.fetchText,