flowdular 0.2.0 → 0.2.1

package/README.md

@@ -71,3 +71,16 @@ Release tooling can import the source distribution API through `flowdular/distri
 - [Documentation](https://github.com/Flowdular/flowdular/tree/main/docs) · [Source and issues](https://github.com/Flowdular/flowdular) · [Website](https://flowdular.com)
 
 Licensed under MIT. Repository documentation and source require repository access while the repositories are private.
+
+## Interactive setup
+
+Run `pnpm flowdular setup` in a terminal. The wizard offers a local demo, existing
+PostgreSQL connection settings, or a configuration check. Local resets require
+confirmation and a stopped application; custom or hosted databases are refused.
+PostgreSQL URLs are masked and saved to `.env` with TLS verification; this does
+not initialize, reset or connect to the hosted database.
+
+Without an interactive terminal, `setup` remains a configuration check. Use
+`setup check --json` for machine-readable results and
+`setup quick --apply --confirm reset-local-auth` for an explicitly authorized
+local reset in a script. Ctrl+C or declining confirmation leaves data unchanged.

package/dist/distribution.js

@@ -3405,7 +3405,7 @@ import { dirname as dirname6, join as join6, relative as relative5 } from "node:
 import { createRequire } from "node:module";
 import { readFile as readFile5 } from "node:fs/promises";
 import { dirname as dirname4, join as join3 } from "node:path";
-var SDK_VERSION = "0.2.0";
+var SDK_VERSION = "0.2.1";
 function npmPackage(specifier) {
   return specifier.startsWith("@") ? specifier.split("/").slice(0, 2).join("/") : specifier.split("/")[0];
 }

package/dist/index.js

@@ -1999,15 +1999,42 @@ function isCapabilityList(values2) {
 }
 function renderOutput(envelope, json2) {
   if (json2) return JSON.stringify(envelope, null, 2);
-  if (!envelope.ok)
-    return `ERROR ${envelope.error?.code ?? "UNKNOWN"}
+  if (!envelope.ok) {
+    const heading = `ERROR ${envelope.error?.code ?? "UNKNOWN"}
 ${envelope.error?.message ?? "Command failed."}`;
+    if (envelope.error?.code !== "DOCTOR_FAILED") return heading;
+    const details = envelope.error.details;
+    if (!Array.isArray(details?.checks)) return heading;
+    const failures = details.checks.filter(
+      (check) => check && check.status === "fail" && typeof check.id === "string" && typeof check.message === "string"
+    );
+    return [
+      heading,
+      ...failures.map((check) => `FAIL ${check.id}  ${check.message}`)
+    ].join("\n");
+  }
   const decorate = (body) => [
     body,
     ...envelope.warnings.map((warning) => `WARNING ${warning}`),
     ...envelope.evidence.map((item) => `EVIDENCE ${item}`)
   ].join("\n");
   const data2 = envelope.data;
+  if (data2?.cancelled === true) return decorate("Setup cancelled.");
+  if (data2?.setup === "postgresql")
+    return decorate(
+      "PostgreSQL settings saved to .env.\nRun pnpm dev, then open http://localhost:4310 to create an account."
+    );
+  if (data2?.setup === "local") {
+    const admin = data2.accounts?.admin;
+    return decorate(
+      [
+        "Local demo is ready.",
+        "Run pnpm dev, then open http://localhost:4310.",
+        ...admin?.email ? [`Demo administrator: ${admin.email}`] : [],
+        ...admin?.password ? [`Public demo password: ${admin.password}`] : []
+      ].join("\n")
+    );
+  }
   if (data2 && Array.isArray(data2.checks)) {
     return decorate(
       data2.checks.map((check) => {
@@ -2026,143 +2053,53 @@ ${envelope.error?.message ?? "Command failed."}`;
   return decorate(JSON.stringify(data2, null, 2));
 }
 
-// ../kernel/src/errors.ts
-var RegistryError = class extends Error {
-  code;
-  constructor(code, message) {
-    super(message);
-    this.name = "RegistryError";
-    this.code = code;
-  }
-};
-
-// ../kernel/src/module-compatibility.ts
-var import_semver = __toESM(require_semver2(), 1);
-var PLATFORM_API_VERSION = "0.1.0";
-function satisfiesModuleVersion(version, range) {
-  return (0, import_semver.valid)(version) !== null && (0, import_semver.validRange)(range) !== null && (0, import_semver.satisfies)(version, range);
-}
-function compareModuleVersions(left, right) {
-  return (0, import_semver.rcompare)(left, right);
-}
-function assertModuleCompatibility(manifest2, platformVersion = PLATFORM_API_VERSION) {
-  if (!(0, import_semver.valid)(manifest2.version))
-    throw new RegistryError(
-      "MODULE_VERSION_INVALID",
-      `Invalid version for ${manifest2.id}: ${manifest2.version}`
-    );
-  if (manifest2.platformApi !== void 0 && (!(0, import_semver.validRange)(manifest2.platformApi) || platformVersion !== null && !satisfiesModuleVersion(platformVersion, manifest2.platformApi))) {
-    throw new RegistryError(
-      "MODULE_PLATFORM_INCOMPATIBLE",
-      `${manifest2.id} requires platform API ${manifest2.platformApi}; available ${PLATFORM_API_VERSION}.`
-    );
-  }
-  const ids = /* @__PURE__ */ new Set();
-  for (const dependency of manifest2.dependencies) {
-    if (!dependency.range.trim() || !(0, import_semver.validRange)(dependency.range))
-      throw new RegistryError(
-        "MODULE_RANGE_INVALID",
-        `${manifest2.id} declares an invalid range for ${dependency.id}: ${dependency.range}`
-      );
-    if (ids.has(dependency.id))
-      throw new RegistryError(
-        "MODULE_DEPENDENCY_DUPLICATE",
-        `${manifest2.id} declares ${dependency.id} more than once.`
-      );
-    ids.add(dependency.id);
-  }
-}
-function assertModuleDependency(consumer, dependency, version) {
-  if (!satisfiesModuleVersion(version, dependency.range)) {
-    throw new RegistryError(
-      "MODULE_DEPENDENCY_INCOMPATIBLE",
-      `${consumer} requires ${dependency.id} ${dependency.range}; available ${version}.`
-    );
-  }
-}
-
-// ../kernel/src/module-registry.ts
-function compareModules(left, right) {
-  return left.manifest.id.localeCompare(right.manifest.id);
-}
-function visitModule(id, modules, visiting, visited, ordered) {
-  if (visited.has(id)) return;
-  if (visiting.has(id)) {
-    throw new RegistryError(
-      "MODULE_DEPENDENCY_CYCLE",
-      `Dependency cycle detected at "${id}".`
-    );
-  }
-  const current = modules.get(id);
-  if (!current) {
-    throw new RegistryError(
-      "MODULE_NOT_FOUND",
-      `Module "${id}" is not registered.`
-    );
-  }
-  visiting.add(id);
-  for (const dependency of [...current.manifest.dependencies].sort(
-    (a, b) => a.id.localeCompare(b.id)
-  )) {
-    if (!modules.has(dependency.id)) {
-      throw new RegistryError(
-        "MODULE_DEPENDENCY_MISSING",
-        `Module "${id}" requires missing module "${dependency.id}".`
+// src/workspace.ts
+import { access, readFile, realpath } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+async function findWorkspace(start) {
+  let directory = resolve(start);
+  for (; ; ) {
+    const configPath = resolve(directory, "flowdular.json");
+    try {
+      await access(configPath);
+      const config = JSON.parse(await readFile(configPath, "utf8"));
+      return { root: directory, configPath, config };
+    } catch (error) {
+      if (error instanceof SyntaxError) throw error;
+    }
+    const parent = dirname(directory);
+    if (parent === directory) {
+      throw new Error(
+        "No flowdular.json was found in this directory or any parent."
       );
     }
-    assertModuleDependency(
-      id,
-      dependency,
-      modules.get(dependency.id).manifest.version
-    );
-    visitModule(dependency.id, modules, visiting, visited, ordered);
+    directory = parent;
   }
-  visiting.delete(id);
-  visited.add(id);
-  ordered.push(current);
 }
-function createModuleRegistry(input) {
-  const byId = /* @__PURE__ */ new Map();
-  const navigationIds = /* @__PURE__ */ new Set();
-  for (const module of input) {
-    assertModuleCompatibility(module.manifest);
-    if (byId.has(module.manifest.id)) {
-      throw new RegistryError(
-        "MODULE_DUPLICATE",
-        `Module "${module.manifest.id}" is registered more than once.`
-      );
-    }
-    byId.set(module.manifest.id, module);
-    for (const item of module.navigation ?? []) {
-      if (navigationIds.has(item.id)) {
-        throw new RegistryError(
-          "NAVIGATION_DUPLICATE",
-          `Navigation contribution "${item.id}" is registered more than once.`
-        );
-      }
-      navigationIds.add(item.id);
-    }
+function resolveInside(root, candidate) {
+  const absolute = isAbsolute(candidate) ? resolve(candidate) : resolve(root, candidate);
+  const pathFromRoot = relative(root, absolute);
+  if (pathFromRoot.startsWith("..") || isAbsolute(pathFromRoot)) {
+    throw new Error(`Path escapes the workspace: ${candidate}`);
   }
-  const ordered = [];
-  const visiting = /* @__PURE__ */ new Set();
-  const visited = /* @__PURE__ */ new Set();
-  for (const module of [...input].sort(compareModules)) {
-    visitModule(module.manifest.id, byId, visiting, visited, ordered);
+  return absolute;
+}
+async function resolveExistingInside(root, candidate) {
+  const canonicalRoot = await realpath(root);
+  const canonicalCandidate = await realpath(resolveInside(root, candidate));
+  const pathFromRoot = relative(canonicalRoot, canonicalCandidate);
+  if (pathFromRoot.startsWith("..") || isAbsolute(pathFromRoot)) {
+    throw new Error(`Path escapes the workspace through a link: ${candidate}`);
   }
-  return Object.freeze({
-    modules: Object.freeze(ordered),
-    get: (id) => byId.get(id),
-    has: (id) => byId.has(id),
-    navigation: (permissions) => Object.freeze(
-      ordered.flatMap((module) => module.navigation ?? []).filter(
-        (item) => !item.permission || permissions?.has(item.permission)
-      ).sort(
-        (left, right) => (left.order ?? 1e3) - (right.order ?? 1e3) || left.id.localeCompare(right.id)
-      )
-    )
-  });
+  return canonicalCandidate;
 }
 
+// src/validation.ts
+import { readdir, readFile as readFile2 } from "node:fs/promises";
+import { basename, dirname as dirname2, join, relative as relative2 } from "node:path";
+import Ajv2020 from "ajv/dist/2020.js";
+import { parse as parseYaml } from "yaml";
+
 // ../contracts/schemas/blueprint.schema.json
 var blueprint_schema_default = {
   $schema: "https://json-schema.org/draft/2020-12/schema",
@@ -2985,19 +2922,7 @@ var projectSchema = project_schema_default;
 var moduleCatalogSchema = module_catalog_schema_default;
 var moduleArtifactSchema = module_artifact_schema_default;
 
-// src/module-catalog.ts
-import { readFile as readFile3, stat } from "node:fs/promises";
-import { dirname as dirname3, resolve as resolve2 } from "node:path";
-
-// src/module-artifact.ts
-import { parse as parseYaml2 } from "yaml";
-import { createHash } from "node:crypto";
-
 // src/validation.ts
-import { readdir, readFile } from "node:fs/promises";
-import { basename, dirname, join, relative } from "node:path";
-import Ajv2020 from "ajv/dist/2020.js";
-import { parse as parseYaml } from "yaml";
 var ajv = new Ajv2020({ allErrors: true, strict: true });
 var validators = {
   application: ajv.compile(projectSchema.properties.application),
@@ -3020,7 +2945,7 @@ function issuesFrom(errors) {
   }));
 }
 async function parseFile(path) {
-  const source = await readFile(path, "utf8");
+  const source = await readFile2(path, "utf8");
   return path.endsWith(".yaml") || path.endsWith(".yml") ? parseYaml(source) : JSON.parse(source);
 }
 async function validateFile(path, validator) {
@@ -3084,7 +3009,7 @@ var blueprintFiles = [
 ];
 async function validateBlueprint(path) {
   const report = await validateFile(path, validators.blueprint);
-  const directory = dirname(path);
+  const directory = dirname2(path);
   const entries = new Set(
     (await readdir(directory)).filter((name) => basename(name) === name)
   );
@@ -3095,14 +3020,177 @@ async function validateBlueprint(path) {
     ...missing.map((name) => ({
       code: "BLUEPRINT_FILE_MISSING",
       message: `Required blueprint file is missing: ${name}`,
-      path: relative(process.cwd(), join(directory, name)),
+      path: relative2(process.cwd(), join(directory, name)),
       severity: "error"
     }))
   ];
   return { ...report, valid: false, issues };
 }
 
+// src/agent-resources.ts
+function agentResource(workspace, key) {
+  const defaults = {
+    policy: ".ai/policies/capabilities.yaml",
+    modelRouting: ".ai/policies/model-routing.yaml",
+    blueprints: ".ai/blueprints"
+  };
+  const agent = workspace.config.agent;
+  const path = agent?.[key] ?? defaults[key];
+  if (typeof path !== "string" || !path)
+    throw new Error(`Invalid agent.${key} path.`);
+  return resolveInside(workspace.root, path);
+}
+function findBlueprintFiles(workspace) {
+  return findNamedFiles(
+    agentResource(workspace, "blueprints"),
+    "blueprint.json"
+  );
+}
+
+// ../kernel/src/errors.ts
+var RegistryError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "RegistryError";
+    this.code = code;
+  }
+};
+
+// ../kernel/src/module-compatibility.ts
+var import_semver = __toESM(require_semver2(), 1);
+var PLATFORM_API_VERSION = "0.1.0";
+function satisfiesModuleVersion(version, range) {
+  return (0, import_semver.valid)(version) !== null && (0, import_semver.validRange)(range) !== null && (0, import_semver.satisfies)(version, range);
+}
+function compareModuleVersions(left, right) {
+  return (0, import_semver.rcompare)(left, right);
+}
+function assertModuleCompatibility(manifest2, platformVersion = PLATFORM_API_VERSION) {
+  if (!(0, import_semver.valid)(manifest2.version))
+    throw new RegistryError(
+      "MODULE_VERSION_INVALID",
+      `Invalid version for ${manifest2.id}: ${manifest2.version}`
+    );
+  if (manifest2.platformApi !== void 0 && (!(0, import_semver.validRange)(manifest2.platformApi) || platformVersion !== null && !satisfiesModuleVersion(platformVersion, manifest2.platformApi))) {
+    throw new RegistryError(
+      "MODULE_PLATFORM_INCOMPATIBLE",
+      `${manifest2.id} requires platform API ${manifest2.platformApi}; available ${PLATFORM_API_VERSION}.`
+    );
+  }
+  const ids = /* @__PURE__ */ new Set();
+  for (const dependency of manifest2.dependencies) {
+    if (!dependency.range.trim() || !(0, import_semver.validRange)(dependency.range))
+      throw new RegistryError(
+        "MODULE_RANGE_INVALID",
+        `${manifest2.id} declares an invalid range for ${dependency.id}: ${dependency.range}`
+      );
+    if (ids.has(dependency.id))
+      throw new RegistryError(
+        "MODULE_DEPENDENCY_DUPLICATE",
+        `${manifest2.id} declares ${dependency.id} more than once.`
+      );
+    ids.add(dependency.id);
+  }
+}
+function assertModuleDependency(consumer, dependency, version) {
+  if (!satisfiesModuleVersion(version, dependency.range)) {
+    throw new RegistryError(
+      "MODULE_DEPENDENCY_INCOMPATIBLE",
+      `${consumer} requires ${dependency.id} ${dependency.range}; available ${version}.`
+    );
+  }
+}
+
+// ../kernel/src/module-registry.ts
+function compareModules(left, right) {
+  return left.manifest.id.localeCompare(right.manifest.id);
+}
+function visitModule(id, modules, visiting, visited, ordered) {
+  if (visited.has(id)) return;
+  if (visiting.has(id)) {
+    throw new RegistryError(
+      "MODULE_DEPENDENCY_CYCLE",
+      `Dependency cycle detected at "${id}".`
+    );
+  }
+  const current = modules.get(id);
+  if (!current) {
+    throw new RegistryError(
+      "MODULE_NOT_FOUND",
+      `Module "${id}" is not registered.`
+    );
+  }
+  visiting.add(id);
+  for (const dependency of [...current.manifest.dependencies].sort(
+    (a, b) => a.id.localeCompare(b.id)
+  )) {
+    if (!modules.has(dependency.id)) {
+      throw new RegistryError(
+        "MODULE_DEPENDENCY_MISSING",
+        `Module "${id}" requires missing module "${dependency.id}".`
+      );
+    }
+    assertModuleDependency(
+      id,
+      dependency,
+      modules.get(dependency.id).manifest.version
+    );
+    visitModule(dependency.id, modules, visiting, visited, ordered);
+  }
+  visiting.delete(id);
+  visited.add(id);
+  ordered.push(current);
+}
+function createModuleRegistry(input) {
+  const byId = /* @__PURE__ */ new Map();
+  const navigationIds = /* @__PURE__ */ new Set();
+  for (const module of input) {
+    assertModuleCompatibility(module.manifest);
+    if (byId.has(module.manifest.id)) {
+      throw new RegistryError(
+        "MODULE_DUPLICATE",
+        `Module "${module.manifest.id}" is registered more than once.`
+      );
+    }
+    byId.set(module.manifest.id, module);
+    for (const item of module.navigation ?? []) {
+      if (navigationIds.has(item.id)) {
+        throw new RegistryError(
+          "NAVIGATION_DUPLICATE",
+          `Navigation contribution "${item.id}" is registered more than once.`
+        );
+      }
+      navigationIds.add(item.id);
+    }
+  }
+  const ordered = [];
+  const visiting = /* @__PURE__ */ new Set();
+  const visited = /* @__PURE__ */ new Set();
+  for (const module of [...input].sort(compareModules)) {
+    visitModule(module.manifest.id, byId, visiting, visited, ordered);
+  }
+  return Object.freeze({
+    modules: Object.freeze(ordered),
+    get: (id) => byId.get(id),
+    has: (id) => byId.has(id),
+    navigation: (permissions) => Object.freeze(
+      ordered.flatMap((module) => module.navigation ?? []).filter(
+        (item) => !item.permission || permissions?.has(item.permission)
+      ).sort(
+        (left, right) => (left.order ?? 1e3) - (right.order ?? 1e3) || left.id.localeCompare(right.id)
+      )
+    )
+  });
+}
+
+// src/module-catalog.ts
+import { readFile as readFile3, stat } from "node:fs/promises";
+import { dirname as dirname3, resolve as resolve2 } from "node:path";
+
 // src/module-artifact.ts
+import { parse as parseYaml2 } from "yaml";
+import { createHash } from "node:crypto";
 var MAX_ARTIFACT_BYTES = 48 * 1024 * 1024;
 var MAX_SOURCE_BYTES = 32 * 1024 * 1024;
 var MAX_FILES = 4096;
@@ -3261,47 +3349,6 @@ function validateModuleArtifact(value) {
   return artifact;
 }
 
-// src/workspace.ts
-import { access, readFile as readFile2, realpath } from "node:fs/promises";
-import { dirname as dirname2, isAbsolute, relative as relative2, resolve } from "node:path";
-async function findWorkspace(start) {
-  let directory = resolve(start);
-  for (; ; ) {
-    const configPath = resolve(directory, "flowdular.json");
-    try {
-      await access(configPath);
-      const config = JSON.parse(await readFile2(configPath, "utf8"));
-      return { root: directory, configPath, config };
-    } catch (error) {
-      if (error instanceof SyntaxError) throw error;
-    }
-    const parent = dirname2(directory);
-    if (parent === directory) {
-      throw new Error(
-        "No flowdular.json was found in this directory or any parent."
-      );
-    }
-    directory = parent;
-  }
-}
-function resolveInside(root, candidate) {
-  const absolute = isAbsolute(candidate) ? resolve(candidate) : resolve(root, candidate);
-  const pathFromRoot = relative2(root, absolute);
-  if (pathFromRoot.startsWith("..") || isAbsolute(pathFromRoot)) {
-    throw new Error(`Path escapes the workspace: ${candidate}`);
-  }
-  return absolute;
-}
-async function resolveExistingInside(root, candidate) {
-  const canonicalRoot = await realpath(root);
-  const canonicalCandidate = await realpath(resolveInside(root, candidate));
-  const pathFromRoot = relative2(canonicalRoot, canonicalCandidate);
-  if (pathFromRoot.startsWith("..") || isAbsolute(pathFromRoot)) {
-    throw new Error(`Path escapes the workspace through a link: ${candidate}`);
-  }
-  return canonicalCandidate;
-}
-
 // src/module-catalog.ts
 var OFFICIAL_CATALOG = "https://raw.githubusercontent.com/Flowdular/official-modules/main/registry/index.json";
 var OFFICIAL_PREFIX = "https://raw.githubusercontent.com/Flowdular/official-modules/";
@@ -3499,7 +3546,7 @@ import { dirname as dirname6, join as join5, relative as relative5 } from "node:
 import { createRequire } from "node:module";
 import { readFile as readFile4 } from "node:fs/promises";
 import { dirname as dirname4, join as join2 } from "node:path";
-var SDK_VERSION = "0.2.0";
+var SDK_VERSION = "0.2.1";
 var LIBRARIES = /* @__PURE__ */ new Set([
   "ai-provider",
   "cli-protocol",
@@ -3591,14 +3638,14 @@ import { createRequire as createRequire2 } from "node:module";
 import { lstat, readFile as readFile5 } from "node:fs/promises";
 import { join as join3, relative as relative3 } from "node:path";
 function moduleRoots(workspace) {
-  const roots = workspace.config.modules?.roots ?? ["modules"];
-  if (!Array.isArray(roots) || !roots.length || roots.some(
+  const roots2 = workspace.config.modules?.roots ?? ["modules"];
+  if (!Array.isArray(roots2) || !roots2.length || roots2.some(
     (root) => typeof root !== "string" || !root || root.startsWith(".") || root.includes("\\") || root.split("/").some((part) => part === ".." || !part)
   ))
     throw new Error(
       "Invalid modules.roots. Use relative workspace directories."
     );
-  return roots.map((root) => {
+  return roots2.map((root) => {
     const path = resolveInside(workspace.root, root);
     if (!relative3(workspace.root, path))
       throw new Error("The workspace root cannot be a module root.");
@@ -4007,10 +4054,10 @@ async function validateModules(workspace, options = {}) {
     );
   }
   try {
-    const registered = manifests.map(
+    const registered2 = manifests.map(
       (manifest2) => ({ manifest: manifest2 })
     );
-    const registry = createModuleRegistry(registered);
+    const registry = createModuleRegistry(registered2);
     const enabled = config.modules?.enabled ?? [];
     const missingEnabled = enabled.filter((id) => !registry.has(id));
     if (missingEnabled.length > 0) {
@@ -6004,19 +6051,35 @@ function createPgliteCluster(options = {}) {
   const close = () => {
     closePromise ??= (async () => {
       if (!databasePromise) return;
-      const instance = await databasePromise;
+      const instance = await databasePromise.catch(() => void 0);
       databasePromise = void 0;
-      await instance.close();
+      await instance?.close();
     })();
     return closePromise;
   };
   const database = async () => {
     databasePromise ??= (async () => {
+      if (options.dataDirectory) {
+        const { mkdir: mkdir6 } = await import("node:fs/promises");
+        await mkdir6(options.dataDirectory, { recursive: true, mode: 448 });
+      }
       const created = options.dataDirectory ? await PGlite.create({
         dataDir: options.dataDirectory,
         parsers: SERVER_PARSERS
       }) : await PGlite.create({ parsers: SERVER_PARSERS });
-      if (options.bootstrap) await created.exec(options.bootstrap);
+      try {
+        if (options.bootstrap) await created.exec(options.bootstrap);
+      } catch (error) {
+        try {
+          await created.close();
+        } catch (closeError) {
+          throw new AggregateError(
+            [error, closeError],
+            "PGlite bootstrap failed and cleanup also failed."
+          );
+        }
+        throw error;
+      }
       return created;
     })();
     return databasePromise;
@@ -6394,8 +6457,8 @@ async function loadManifests(workspace) {
   }
   return descriptors;
 }
-function moduleOrder(manifests, roots, includeDependencies) {
-  const requested = new Set(roots);
+function moduleOrder(manifests, roots2, includeDependencies) {
+  const requested = new Set(roots2);
   const visiting = [];
   const visited = /* @__PURE__ */ new Set();
   const ordered = [];
@@ -6739,14 +6802,15 @@ async function runDoctor(workspace) {
     message: project.valid ? "Project contract is valid." : project.issues.map((issue2) => issue2.message).join("; "),
     evidence: relative6(workspace.root, workspace.configPath)
   });
-  for (const [id, path] of [
-    ["policy.capabilities", ".ai/policies/capabilities.yaml"],
-    ["policy.model-routing", ".ai/policies/model-routing.yaml"],
-    ["blueprints.root", ".ai/blueprints"],
-    ["modules.root", "modules"],
-    ["packages.root", "packages"],
-    ["platform.root", "platform"]
+  for (const [id, resource] of [
+    ["policy.capabilities", agentResource(workspace, "policy")],
+    ["policy.model-routing", agentResource(workspace, "modelRouting")],
+    ["blueprints.root", agentResource(workspace, "blueprints")],
+    ["modules.root", join9(workspace.root, "modules")],
+    ...(await sdkModules(workspace)).size ? [] : [["packages.root", join9(workspace.root, "packages")]],
+    ["platform.root", join9(workspace.root, "platform")]
   ]) {
+    const path = relative6(workspace.root, resource);
     checks.push({
       id,
       status: await exists3(join9(workspace.root, path)) ? "pass" : "fail",
@@ -6763,7 +6827,7 @@ async function runDoctor(workspace) {
     message: packageJson2.packageManager ? `Pinned package manager: ${packageJson2.packageManager}` : "packageManager must pin pnpm.",
     evidence: "package.json"
   });
-  const blueprints = await findNamedFiles(workspace.root, "blueprint.json");
+  const blueprints = await findBlueprintFiles(workspace);
   checks.push({
     id: "blueprints.discovered",
     status: blueprints.length > 0 ? "pass" : "fail",
@@ -6792,8 +6856,56 @@ async function runDoctor(workspace) {
 
 // src/extensions.ts
 import { readFile as readFile11 } from "node:fs/promises";
-import { dirname as dirname9, relative as relative7 } from "node:path";
-import { pathToFileURL as pathToFileURL2 } from "node:url";
+import { dirname as dirname10, relative as relative7 } from "node:path";
+
+// src/module-import.ts
+import { readFileSync as readFileSync2, realpathSync } from "node:fs";
+import {
+  createRequire as createRequire4,
+  registerHooks,
+  stripTypeScriptTypes
+} from "node:module";
+import { dirname as dirname9, sep as sep2 } from "node:path";
+import { fileURLToPath, pathToFileURL as pathToFileURL2 } from "node:url";
+var roots = /* @__PURE__ */ new Set();
+var registered = false;
+async function importModuleSource(entry, moduleRoot) {
+  roots.add(realpathSync(moduleRoot));
+  try {
+    const require2 = createRequire4(pathToFileURL2(entry));
+    roots.add(
+      realpathSync(dirname9(require2.resolve("@flowdular/sdk/package.json")))
+    );
+  } catch (error) {
+    if (!["MODULE_NOT_FOUND", "ERR_PACKAGE_PATH_NOT_EXPORTED"].includes(
+      error.code ?? ""
+    ))
+      throw error;
+  }
+  if (!registered) {
+    registerHooks({
+      load(url, context, nextLoad) {
+        if (!url.startsWith("file:") || !fileURLToPath(url).endsWith(".ts"))
+          return nextLoad(url, context);
+        const path = realpathSync(fileURLToPath(url));
+        if (![...roots].some((root) => path.startsWith(root + sep2)))
+          return nextLoad(url, context);
+        return {
+          format: "module",
+          source: stripTypeScriptTypes(readFileSync2(path, "utf8"), {
+            mode: "transform",
+            sourceUrl: url
+          }),
+          shortCircuit: true
+        };
+      }
+    });
+    registered = true;
+  }
+  return import(pathToFileURL2(entry).href);
+}
+
+// src/extensions.ts
 var reservedGroups = /* @__PURE__ */ new Set([
   "help",
   "doctor",
@@ -6849,7 +6961,10 @@ function commandKey(command) {
   return JSON.stringify({ path: command.path, capability: command.capability });
 }
 async function loadCliCommand(loaded) {
-  const imported = await import(pathToFileURL2(loaded.entry).href);
+  const imported = await importModuleSource(
+    loaded.entry,
+    loaded.moduleRoot
+  );
   const extension = imported.default ?? imported.cliExtension;
   if (!extension) {
     throw new Error(
@@ -6882,7 +6997,7 @@ async function loadCliExtensions(workspace) {
       await readFile11(manifestPath, "utf8")
     );
     if (!enabled.has(manifest2.id) || !manifest2.cli) continue;
-    const moduleRoot = dirname9(manifestPath);
+    const moduleRoot = dirname10(manifestPath);
     const entry = await resolveExistingInside(moduleRoot, manifest2.cli.entry);
     const catalogPath = await resolveExistingInside(
       moduleRoot,
@@ -6919,9 +7034,8 @@ async function loadCliExtensions(workspace) {
 }
 
 // src/migration.ts
-import { readFile as readFile13 } from "node:fs/promises";
-import { dirname as dirname10, join as join11 } from "node:path";
-import { pathToFileURL as pathToFileURL3 } from "node:url";
+import { readFile as readFile13, stat as stat2 } from "node:fs/promises";
+import { dirname as dirname11, join as join11 } from "node:path";
 
 // src/migration-audit.ts
 import { readdir as readdir5, readFile as readFile12 } from "node:fs/promises";
@@ -7085,13 +7199,17 @@ async function loadMigrationModules(workspace, moduleId) {
     );
     if (!enabled.has(manifest2.id)) continue;
     if (moduleId && manifest2.id !== moduleId) continue;
-    const entry = join11(dirname10(manifestPath), "src/services/migration.ts");
-    let databaseMigrations;
+    const entry = join11(dirname11(manifestPath), "src/services/migration.ts");
     try {
-      ({ databaseMigrations } = await import(pathToFileURL3(entry).href));
-    } catch {
-      continue;
+      await stat2(entry);
+    } catch (error) {
+      if (error.code === "ENOENT") continue;
+      throw error;
     }
+    const { databaseMigrations } = await importModuleSource(
+      entry,
+      dirname11(manifestPath)
+    );
     if (!Array.isArray(databaseMigrations)) {
       unmanaged.push({
         moduleId: manifest2.id,
@@ -7101,7 +7219,7 @@ async function loadMigrationModules(workspace, moduleId) {
     }
     managed.push({
       moduleId: manifest2.id,
-      moduleDirectory: dirname10(manifestPath),
+      moduleDirectory: dirname11(manifestPath),
       databaseMigrations
     });
   }
@@ -7328,7 +7446,7 @@ import {
   rm as rm3,
   writeFile as writeFile4
 } from "node:fs/promises";
-import { dirname as dirname11, join as join12, relative as relative8, resolve as resolve5 } from "node:path";
+import { dirname as dirname12, join as join12, relative as relative8, resolve as resolve5 } from "node:path";
 import { parse as parseYaml4 } from "yaml";
 
 // src/module-templates.ts
@@ -8697,7 +8815,7 @@ async function writeScaffold(moduleDirectory, files, target) {
     for (const [path, source] of files) {
       if (target.present.has(path)) continue;
       const absolute = join12(moduleDirectory, path);
-      const created = await mkdir4(dirname11(absolute), { recursive: true });
+      const created = await mkdir4(dirname12(absolute), { recursive: true });
       if (created) createdDirectories.push(created);
       await writeFile4(absolute, source, { encoding: "utf8", flag: "wx" });
       written.push(absolute);
@@ -8797,9 +8915,9 @@ import {
   mkdir as mkdir5,
   readFile as readFile15,
   rm as rm4,
-  stat as stat2
+  stat as stat3
 } from "node:fs/promises";
-import { dirname as dirname12, join as join13, relative as relative9 } from "node:path";
+import { dirname as dirname13, join as join13, relative as relative9 } from "node:path";
 import { createHash as createHash3 } from "node:crypto";
 
 // ../kernel/src/legacy-local-state.ts
@@ -8923,7 +9041,7 @@ async function ensurePrivateDirectory(path) {
   await chmod(path, 448);
 }
 async function copyPlan(plan) {
-  await ensurePrivateDirectory(dirname12(plan.destinationDirectory));
+  await ensurePrivateDirectory(dirname13(plan.destinationDirectory));
   await ensurePrivateDirectory(plan.destinationDirectory);
   const created = [];
   try {
@@ -8932,14 +9050,14 @@ async function copyPlan(plan) {
       if (sourceState.isSymbolicLink() || !sourceState.isFile()) {
         throw new Error(`${file.name} is no longer a regular file.`);
       }
-      const before = await stat2(file.source);
+      const before = await stat3(file.source);
       await copyFile(file.source, file.destination, constants.COPYFILE_EXCL);
       created.push(file.destination);
       await chmod(file.destination, 384);
       const [sourceDigest2, destinationDigest, after] = await Promise.all([
         digest(file.source),
         digest(file.destination),
-        stat2(file.source)
+        stat3(file.source)
       ]);
       if (sourceDigest2 !== destinationDigest || before.size !== after.size || before.mtimeMs !== after.mtimeMs) {
         throw new Error(`Source changed while copying ${file.name}.`);
@@ -8979,7 +9097,7 @@ function data(plan, applied) {
     ready: plan.blockers.length === 0,
     source: LEGACY_DATA_DIRECTORY,
     destination: relative9(
-      dirname12(dirname12(plan.destinationDirectory)),
+      dirname13(dirname13(plan.destinationDirectory)),
       plan.destinationDirectory
     ),
     files: plan.files.map((file) => file.name),
@@ -9163,7 +9281,7 @@ async function runCommand(arguments_) {
           "module list|validate [--locked]|sync [--apply]|enable <id> [--apply]|disable <id> [--apply]|new <id> --spec <path> [--apply]",
           "migration status [--module <id>]|apply --module <id> [--apply]|verify|new <name> --module <id> [--apply]",
           "database reset [--module <id>] [--apply --confirm reset-database]",
-          "setup check|quick [--apply --confirm reset-local-auth]|migrate-state [--apply --confirm migrate-legacy-state]",
+          "setup (interactive)|check|quick [--apply --confirm reset-local-auth]|migrate-state [--apply --confirm migrate-legacy-state]",
           ...extensionCommands.map((entry) => entry.command.path.join(" "))
         ],
         options: [
@@ -9281,13 +9399,13 @@ async function runCommand(arguments_) {
       );
     }
     if (group === "blueprint" && action === "list") {
-      const files = await findNamedFiles(workspace.root, "blueprint.json");
+      const files = await findBlueprintFiles(workspace);
       return success({
         blueprints: files.map((file) => relative10(workspace.root, file))
       });
     }
     if (group === "blueprint" && action === "validate") {
-      const files = await findNamedFiles(workspace.root, "blueprint.json");
+      const files = await findBlueprintFiles(workspace);
       const reports = await Promise.all(files.map(validateBlueprint));
       const data2 = relativeReports2(workspace.root, reports);
       return reports.every((report) => report.valid) ? success(
@@ -9584,11 +9702,213 @@ async function runProgram(arguments_) {
   }
 }
 
+// src/setup-wizard.ts
+import { stat as stat4 } from "node:fs/promises";
+
+// src/setup-environment.ts
+import { randomUUID } from "node:crypto";
+import { lstat as lstat4, open, readFile as readFile17, rename as rename2, rm as rm5, writeFile as writeFile5 } from "node:fs/promises";
+import { join as join15 } from "node:path";
+async function readSetupEnvironment(root) {
+  try {
+    return await readFile17(join15(root, ".env"), "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return "";
+    throw error;
+  }
+}
+async function saveSetupEnvironment(root, before, updates) {
+  const path = join15(root, ".env");
+  try {
+    if (!(await lstat4(path)).isFile())
+      throw new Error("Setup requires .env to be a regular file.");
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  for (const [key, value] of Object.entries(updates)) {
+    if (!/^FD_DATABASE_[A-Z_]+$/.test(key) || /[\r\n'\0]/.test(value))
+      throw new Error("Invalid database setting.");
+  }
+  const lines = before.split(/\r?\n/).filter((line) => {
+    const match = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(
+      line
+    );
+    if (!match || !(match[1] in updates)) return true;
+    const value = match[2].trim();
+    if (value.startsWith('"') && !value.endsWith('"') || value.startsWith("'") && !value.endsWith("'"))
+      throw new Error(
+        "Edit multiline database settings in .env before using setup."
+      );
+    return false;
+  });
+  const source = lines.join("\n").trimEnd() + "\n" + Object.entries(updates).map(([key, value]) => `${key}='${value}'`).join("\n") + "\n";
+  const temporary = join15(root, `.env.setup-${randomUUID()}.tmp`);
+  const lockPath = join15(root, ".env.setup.lock");
+  const lock = await open(lockPath, "wx", 384);
+  try {
+    await writeFile5(temporary, source, { mode: 384, flag: "wx" });
+    if (await readSetupEnvironment(root) !== before)
+      throw new Error("The .env file changed during setup. Run setup again.");
+    await rename2(temporary, path);
+  } finally {
+    try {
+      await rm5(temporary, { force: true });
+    } finally {
+      await lock.close();
+      await rm5(lockPath, { force: true });
+    }
+  }
+}
+
+// src/setup-wizard.ts
+var prompts = {
+  async choose() {
+    const { select } = await import("@inquirer/prompts");
+    return select({
+      message: "How would you like to set up this application?",
+      choices: [
+        {
+          name: "Local demo with embedded PostgreSQL (PGlite)",
+          value: "local"
+        },
+        {
+          name: "Configure an existing PostgreSQL database",
+          value: "postgresql"
+        },
+        { name: "Check configuration only", value: "check" }
+      ]
+    });
+  },
+  async confirm(message) {
+    const { confirm } = await import("@inquirer/prompts");
+    return confirm({ message, default: false });
+  },
+  async connection(message) {
+    const { password } = await import("@inquirer/prompts");
+    return password({
+      message,
+      mask: "*",
+      validate: (value) => validConnection(value) ? true : "Use postgres://user:password@host/database without SSL query parameters."
+    });
+  }
+};
+function validConnection(value) {
+  if (value.length > 4096 || /[\r\n'\0]/.test(value)) return false;
+  try {
+    const url = new URL(value);
+    return ["postgres:", "postgresql:"].includes(url.protocol) && Boolean(url.hostname && url.username && url.pathname.length > 1) && !["sslmode", "sslcert", "sslkey", "sslrootcert"].some(
+      (key) => url.searchParams.has(key)
+    );
+  } catch {
+    return false;
+  }
+}
+async function runSetupWizard(arguments_, io = prompts, execute = runProgram) {
+  try {
+    const flags = new Map(arguments_.flags);
+    flags.delete("apply");
+    flags.delete("confirm");
+    const check = await execute({ positionals: ["setup", "check"], flags });
+    if (!check.ok) return check;
+    const workspace = await findWorkspace(
+      stringFlag(arguments_, "root") ?? process.cwd()
+    );
+    const before = await readSetupEnvironment(workspace.root);
+    const choice = await io.choose();
+    if (choice === "check") return check;
+    if (choice === "postgresql") {
+      const urls = {
+        FD_DATABASE_URL: await io.connection("Runtime role connection URL"),
+        FD_DATABASE_MIGRATOR_URL: await io.connection(
+          "Migration role connection URL"
+        ),
+        FD_DATABASE_BACKGROUND_URL: await io.connection(
+          "Background role connection URL"
+        )
+      };
+      if (!Object.values(urls).every(validConnection))
+        return failure(
+          "INVALID_DATABASE_CONFIGURATION",
+          "Invalid PostgreSQL connection settings."
+        );
+      const updates = {
+        ...urls,
+        FD_DATABASE_ADAPTER: "postgresql",
+        FD_DATABASE_TLS: "verify-full"
+      };
+      databaseProviderConfigFromEnvironment(
+        { ...process.env, ...updates, NODE_ENV: "production" },
+        workspace.root
+      );
+      if (!await io.confirm(
+        "Save PostgreSQL settings in .env? This does not reset or modify the hosted database."
+      ))
+        return success({ cancelled: true });
+      await saveSetupEnvironment(workspace.root, before, updates);
+      return success(
+        {
+          setup: "postgresql",
+          configured: true,
+          adapter: "postgresql",
+          next: "Run pnpm dev, then open http://localhost:4310 and create an account."
+        },
+        {
+          warnings: [
+            "TLS certificate verification is enabled. The database must provide separate migration, runtime and background roles."
+          ]
+        }
+      );
+    }
+    const config = databaseProviderConfigFromEnvironment(
+      process.env,
+      workspace.root
+    );
+    if (config.adapter !== "pglite" || process.env.FD_DATABASE_PGLITE_DIRECTORY || process.env.CORELOOM_DATABASE_PGLITE_DIRECTORY || process.env.FD_DATABASE_URL || process.env.CORELOOM_DATABASE_URL)
+      return failure(
+        "LOCAL_DEMO_UNAVAILABLE",
+        "Local demo setup requires the default embedded database. The configured database will not be reset."
+      );
+    const preview = await execute({ positionals: ["setup", "quick"], flags });
+    if (!preview.ok) return preview;
+    const directory = config.pglite?.dataDirectory;
+    let existing = false;
+    if (directory)
+      try {
+        await stat4(directory);
+        existing = true;
+      } catch (error) {
+        if (error.code !== "ENOENT") throw error;
+      }
+    const message = existing ? `Reset the local demo database in ${directory}? All existing local data will be deleted. Confirm that the app is stopped.` : "Create a local demo with admin@example.com? Confirm that the app is stopped.";
+    if (!await io.confirm(message)) return success({ cancelled: true });
+    if (await readSetupEnvironment(workspace.root) !== before)
+      return failure(
+        "SETUP_CONFIGURATION_CHANGED",
+        "The .env file changed during setup. Run setup again."
+      );
+    flags.set("apply", true);
+    flags.set("confirm", "reset-local-auth");
+    const applied = await execute({ positionals: ["setup", "quick"], flags });
+    return applied.ok ? success(
+      { ...applied.data, setup: "local" },
+      { warnings: applied.warnings, evidence: applied.evidence }
+    ) : applied;
+  } catch (error) {
+    if (error instanceof Error && ["ExitPromptError", "AbortPromptError"].includes(error.name))
+      return success({ cancelled: true });
+    return failure(
+      "SETUP_FAILED",
+      error instanceof Error ? error.message : "Setup failed."
+    );
+  }
+}
+
 // src/index.ts
 var invokedAsProgram = process.argv[1]?.endsWith("/index.ts") || process.argv[1]?.endsWith("/index.js");
 if (invokedAsProgram) {
   const arguments_ = parseArguments(process.argv.slice(2));
-  const envelope = await runProgram(arguments_);
+  const interactive = arguments_.positionals.length === 1 && arguments_.positionals[0] === "setup" && !arguments_.flags.has("json") && !arguments_.flags.has("help") && process.stdin.isTTY && process.stdout.isTTY;
+  const envelope = await (interactive ? runSetupWizard(arguments_) : runProgram(arguments_));
   process.stdout.write(
     `${renderOutput(envelope, arguments_.flags.has("json"))}
 `

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "flowdular",
-	"version": "0.2.0",
+	"version": "0.2.1",
 	"type": "module",
 	"bin": {
 		"flowdular": "./dist/index.js",
@@ -12,10 +12,11 @@
 	},
 	"dependencies": {
 		"@electric-sql/pglite": "0.5.8",
+		"@inquirer/prompts": "8.7.2",
 		"ajv": "8.20.0",
 		"pg": "8.23.0",
 		"yaml": "2.9.0",
-		"@flowdular/sdk": "0.2.0"
+		"@flowdular/sdk": "0.2.1"
 	},
 	"license": "MIT",
 	"repository": {