facult 2.17.10 → 2.17.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "facult",
-  "version": "2.17.10",
+  "version": "2.17.12",
   "description": "Manage canonical AI capabilities, sync surfaces, and evolution state.",
   "type": "module",
   "license": "MIT",

package/src/doctor.ts

@@ -609,6 +609,22 @@ const UNRESOLVED_REFS_TEMPLATE_RE = /\$\{refs\.([A-Za-z0-9_.-]+)\}/g;
 const FCLTY_BLOCK_RE =
   /<!--\s*fclty:([^>]+?)\s*-->([\s\S]*?)<!--\s*\/fclty:\1\s*-->/g;
 
+function shellQuote(value: string): string {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+function projectAiInitCommand(rootDir: string, flags: string[] = []): string {
+  const projectRoot = projectRootFromAiRoot(rootDir);
+  const rootFlag = projectRoot ? "--project-root" : "--root";
+  const rootValue = projectRoot ?? rootDir;
+  return [
+    "fclt templates init project-ai",
+    rootFlag,
+    shellQuote(rootValue),
+    ...flags,
+  ].join(" ");
+}
+
 async function inspectCanonicalGlobalDocs(
   rootDir: string,
   opts: { projectRoot?: string | null } = {}
@@ -625,7 +641,7 @@ async function inspectCanonicalGlobalDocs(
   const text = await readFile(pathValue, "utf8");
   const issues: DoctorIssue[] = [];
   const refreshCommand = opts.projectRoot
-    ? "fclt templates init project-ai --force"
+    ? projectAiInitCommand(rootDir, ["--force"])
     : "fclt templates init operating-model --global --force";
   const docLabel = opts.projectRoot
     ? "project AGENTS.global.md"
@@ -1025,7 +1041,7 @@ export async function buildDoctorReport(opts?: {
       message:
         "No canonical capability source was found in the selected .ai root.",
       fix: projectRoot
-        ? "Run fclt templates init project-ai from the repo or restore canonical project assets."
+        ? `Run ${projectAiInitCommand(rootDir)} or restore canonical project assets.`
         : "Run fclt templates init operating-model --global.",
     });
   }
@@ -1042,7 +1058,7 @@ export async function buildDoctorReport(opts?: {
         ? "Refresh project operating model"
         : "Refresh global operating model",
       command: projectRoot
-        ? "fclt templates init project-ai --force"
+        ? projectAiInitCommand(rootDir, ["--force"])
         : "fclt templates init operating-model --global --force",
       risk: "canonical_write",
     });
@@ -1076,7 +1092,7 @@ export async function buildDoctorReport(opts?: {
     actions.push({
       id: "init-project-ai",
       label: "Initialize project AI root",
-      command: "fclt templates init project-ai",
+      command: projectAiInitCommand(rootDir),
       risk: "canonical_write",
     });
   }

package/src/remote.ts

@@ -1576,14 +1576,23 @@ async function scaffoldBuiltinOperatingModelPack(args: {
 
 async function scaffoldBuiltinProjectAiPack(args: {
   cwd?: string;
+  rootDir?: string;
   homeDir?: string;
   dryRun?: boolean;
   force?: boolean;
   update?: boolean;
 }): Promise<InstallResult> {
   const cwd = resolve(args.cwd ?? process.cwd());
+  const rootDir = args.rootDir
+    ? resolveCliContextRoot({
+        rootArg: args.rootDir,
+        scope: "project",
+        cwd,
+        homeDir: args.homeDir,
+      })
+    : join(cwd, ".ai");
   return await scaffoldBuiltinOperatingModelPack({
-    rootDir: join(cwd, ".ai"),
+    rootDir,
     homeDir: args.homeDir,
     dryRun: args.dryRun,
     force: args.force,
@@ -3039,7 +3048,7 @@ function printTemplatesHelp() {
               "fclt templates init operating-model [--global|--project|--root PATH] [--update] [--force] [--dry-run]"
             ),
             renderCode(
-              "fclt templates init project-ai [--update] [--force] [--dry-run]"
+              "fclt templates init project-ai [--project-root PATH|--root PATH] [--update] [--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]"
@@ -3115,16 +3124,22 @@ const TEMPLATE_INIT_VALUE_FLAGS = new Set([
 function parseTemplateInitArgs(argv: string[]): {
   positional: string[];
   rootArg?: string;
+  projectRootArg?: string;
 } {
   const positional: string[] = [];
   let rootArg: string | undefined;
+  let projectRootArg: 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;
+      const value = argv[i + 1];
+      if (!value || value.startsWith("-")) {
+        throw new Error("--root requires a path value");
+      }
+      rootArg = value;
       i += 1;
       continue;
     }
@@ -3132,6 +3147,19 @@ function parseTemplateInitArgs(argv: string[]): {
       rootArg = arg.slice("--root=".length);
       continue;
     }
+    if (arg === "--project-root") {
+      const value = argv[i + 1];
+      if (!value || value.startsWith("-")) {
+        throw new Error("--project-root requires a path value");
+      }
+      projectRootArg = value;
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith("--project-root=")) {
+      projectRootArg = arg.slice("--project-root=".length);
+      continue;
+    }
     if (TEMPLATE_INIT_VALUE_FLAGS.has(arg)) {
       i += 1;
       continue;
@@ -3145,7 +3173,22 @@ function parseTemplateInitArgs(argv: string[]): {
     }
     positional.push(arg);
   }
-  return { positional, rootArg };
+  return { positional, rootArg, projectRootArg };
+}
+
+function expandHomePath(pathValue: string, homeDir: string): string {
+  if (pathValue === "~") {
+    return homeDir;
+  }
+  if (pathValue.startsWith("~/")) {
+    return `${homeDir}/${pathValue.slice(2)}`;
+  }
+  return pathValue;
+}
+
+function projectAiRootFromProjectArg(value: string, homeDir?: string): string {
+  const resolved = resolve(expandHomePath(value, homeDir ?? homedir()));
+  return basename(resolved) === ".ai" ? resolved : join(resolved, ".ai");
 }
 
 export async function sourcesCommand(
@@ -3543,6 +3586,10 @@ export async function templatesCommand(
     process.exitCode = 2;
     return;
   }
+  if (args.includes("--help") || args.includes("-h") || args[0] === "help") {
+    printTemplatesHelp();
+    return;
+  }
   const dryRun = args.includes("--dry-run");
   const force = args.includes("--force");
   const update = args.includes("--update");
@@ -3554,6 +3601,15 @@ export async function templatesCommand(
     try {
       const result = await scaffoldBuiltinProjectAiPack({
         cwd: ctx.cwd,
+        rootDir:
+          parsedArgs.rootArg ??
+          ctx.rootDir ??
+          (parsedArgs.projectRootArg
+            ? projectAiRootFromProjectArg(
+                parsedArgs.projectRootArg,
+                ctx.homeDir
+              )
+            : undefined),
         homeDir: ctx.homeDir,
         dryRun,
         force,