qavor 0.1.0

package/dist/index.js

@@ -0,0 +1,2883 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import process2 from "process";
+import { Command } from "commander";
+
+// src/util/exit-codes.ts
+var ExitCode = {
+  Ok: 0,
+  UserError: 1,
+  ManifestError: 2,
+  RuntimeError: 3
+};
+var QavorError = class extends Error {
+  exitCode;
+  constructor(message, exitCode = ExitCode.RuntimeError) {
+    super(message);
+    this.name = "QavorError";
+    this.exitCode = exitCode;
+  }
+};
+var UserError = class extends QavorError {
+  constructor(message) {
+    super(message, ExitCode.UserError);
+    this.name = "UserError";
+  }
+};
+var ManifestError = class extends QavorError {
+  constructor(message) {
+    super(message, ExitCode.ManifestError);
+    this.name = "ManifestError";
+  }
+};
+var RuntimeFailure = class extends QavorError {
+  constructor(message) {
+    super(message, ExitCode.RuntimeError);
+    this.name = "RuntimeFailure";
+  }
+};
+
+// src/util/logger.ts
+import pino from "pino";
+var rootLogger = null;
+function configureLogger(opts) {
+  const level = opts.verbose ? "debug" : "info";
+  const stderrIsTty = Boolean(process.stderr.isTTY);
+  if (opts.json || !stderrIsTty) {
+    rootLogger = pino({ level }, pino.destination({ fd: 2, sync: true }));
+  } else {
+    rootLogger = pino({
+      level,
+      transport: {
+        target: "pino-pretty",
+        options: {
+          destination: 2,
+          colorize: stderrIsTty,
+          translateTime: false,
+          ignore: "pid,hostname,time",
+          messageFormat: "{msg}",
+          singleLine: false,
+          sync: true
+        }
+      }
+    });
+  }
+  return rootLogger;
+}
+function getLogger() {
+  if (!rootLogger) {
+    rootLogger = pino({ level: "info" });
+  }
+  return rootLogger;
+}
+function emit(text) {
+  process.stdout.write(text + "\n");
+}
+function emitJson(payload) {
+  process.stdout.write(JSON.stringify(payload) + "\n");
+}
+
+// src/cli/commands/init.ts
+import path6 from "path";
+
+// src/workspace/init.ts
+import { createHash as createHash2 } from "crypto";
+import fs4 from "fs/promises";
+import path5 from "path";
+
+// src/util/fs.ts
+import { createHash } from "crypto";
+import { createReadStream } from "fs";
+import fs from "fs/promises";
+import path from "path";
+async function pathExists(target) {
+  try {
+    await fs.access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function isDirectory(target) {
+  try {
+    const s = await fs.stat(target);
+    return s.isDirectory();
+  } catch {
+    return false;
+  }
+}
+async function isFile(target) {
+  try {
+    const s = await fs.stat(target);
+    return s.isFile();
+  } catch {
+    return false;
+  }
+}
+async function ensureDir(target) {
+  await fs.mkdir(target, { recursive: true });
+}
+async function readJsonFile(target) {
+  const raw = await fs.readFile(target, "utf8");
+  return JSON.parse(raw);
+}
+async function writeJsonFile(target, value) {
+  await ensureDir(path.dirname(target));
+  await fs.writeFile(target, JSON.stringify(value, null, 2) + "\n", "utf8");
+}
+function globalCacheDir(env = process.env) {
+  const xdg = env.XDG_CACHE_HOME;
+  if (xdg && xdg.length > 0) return path.join(xdg, "qavor");
+  const home = env.HOME ?? env.USERPROFILE ?? "/tmp";
+  return path.join(home, ".cache", "qavor");
+}
+
+// src/git/git.ts
+import { execa } from "execa";
+import fs2 from "fs/promises";
+import path2 from "path";
+import simpleGit from "simple-git";
+async function runGit(args, opts) {
+  let child;
+  try {
+    child = execa("git", args, {
+      cwd: opts.cwd,
+      env: opts.env ? { ...process.env, ...opts.env } : process.env,
+      ...opts.signal ? { cancelSignal: opts.signal } : {},
+      stdout: "pipe",
+      stderr: "pipe"
+    });
+    const res = await child;
+    return typeof res.stdout === "string" ? res.stdout : "";
+  } catch (err) {
+    const ee = err;
+    const stderr = typeof ee.stderr === "string" ? ee.stderr : "";
+    const stdout = typeof ee.stdout === "string" ? ee.stdout : "";
+    const code2 = ee.exitCode ?? -1;
+    const tail = stderr.trim() || stdout.trim() || ee.shortMessage || ee.message;
+    throw new RuntimeFailure(`git ${args.join(" ")} (exit ${code2}) in ${opts.cwd}
+  ${tail}`);
+  }
+}
+async function isGitRepo(dir) {
+  if (!await isDirectory(dir)) return false;
+  try {
+    await fs2.access(path2.join(dir, ".git"));
+    return true;
+  } catch {
+    try {
+      const out = await runGit(["rev-parse", "--is-inside-work-tree"], { cwd: dir });
+      return out.trim() === "true";
+    } catch {
+      return false;
+    }
+  }
+}
+async function readRepoStatus(dir) {
+  const git = simpleGit({ baseDir: dir });
+  let branch = null;
+  try {
+    const summary = await git.branch();
+    branch = summary.current || null;
+  } catch {
+    branch = null;
+  }
+  let ahead = 0;
+  let behind = 0;
+  try {
+    const counts = await runGit(["rev-list", "--left-right", "--count", "@{u}...HEAD"], { cwd: dir });
+    const [b, a] = counts.trim().split(/\s+/).map((n) => Number.parseInt(n, 10));
+    behind = Number.isFinite(b) ? b ?? 0 : 0;
+    ahead = Number.isFinite(a) ? a ?? 0 : 0;
+  } catch {
+  }
+  let dirtyCount = 0;
+  try {
+    const status = await git.status();
+    dirtyCount = status.files.length;
+  } catch {
+  }
+  let lastCommit = null;
+  let lastCommitSubject = null;
+  try {
+    const log = await git.log({ maxCount: 1 });
+    if (log.latest) {
+      lastCommit = log.latest.hash.slice(0, 7);
+      lastCommitSubject = log.latest.message;
+    }
+  } catch {
+  }
+  return { branch, ahead, behind, dirtyCount, lastCommit, lastCommitSubject };
+}
+async function gitClone(opts) {
+  const args = ["clone"];
+  if (opts.branch && !opts.commit) args.push("--branch", opts.branch);
+  else if (opts.tag && !opts.commit) args.push("--branch", opts.tag);
+  if (opts.shallow) args.push("--depth", "1");
+  if (opts.submodules) args.push("--recurse-submodules");
+  args.push("--", opts.url, opts.dest);
+  await fs2.mkdir(path2.dirname(opts.dest), { recursive: true });
+  const runOpts = { cwd: path2.dirname(opts.dest) };
+  if (opts.signal) runOpts.signal = opts.signal;
+  await runGit(args, runOpts);
+  if (opts.commit) {
+    const checkoutOpts = { cwd: opts.dest };
+    if (opts.signal) checkoutOpts.signal = opts.signal;
+    await runGit(["checkout", opts.commit], checkoutOpts);
+  }
+}
+async function gitFetch(dir, signal) {
+  const opts = { cwd: dir };
+  if (signal) opts.signal = signal;
+  await runGit(["fetch", "--prune"], opts);
+}
+async function gitPullFastForward(dir, signal) {
+  const opts = { cwd: dir };
+  if (signal) opts.signal = signal;
+  await runGit(["pull", "--ff-only"], opts);
+}
+async function gitCommit(dir, message, opts = {}) {
+  const status = await runGit(["status", "--porcelain"], { cwd: dir });
+  if (status.trim().length === 0 && !opts.allowEmpty) {
+    return { committed: false };
+  }
+  const addOpts = { cwd: dir };
+  if (opts.signal) addOpts.signal = opts.signal;
+  await runGit(["add", "-A"], addOpts);
+  const args = ["commit", "-m", message];
+  if (opts.allowEmpty) args.push("--allow-empty");
+  const commitOpts = { cwd: dir };
+  if (opts.signal) commitOpts.signal = opts.signal;
+  await runGit(args, commitOpts);
+  return { committed: true };
+}
+async function gitPush(dir, signal) {
+  const opts = { cwd: dir };
+  if (signal) opts.signal = signal;
+  await runGit(["push"], opts);
+}
+function deriveCloneUrl(input) {
+  if (input.explicitUrl) return input.explicitUrl;
+  if (!input.rootUrl) {
+    throw new RuntimeFailure(
+      `Cannot derive clone URL for '${input.name}': project manifest has no git.root_url and no explicit url is set.`
+    );
+  }
+  const prefix = input.repoPrefix ?? "";
+  const base = input.rootUrl.endsWith("/") ? input.rootUrl.slice(0, -1) : input.rootUrl;
+  const fullName = `${prefix}${input.name}`;
+  return `${base}/${fullName}.git`;
+}
+
+// src/manifest/loader.ts
+import fs3 from "fs/promises";
+import path3 from "path";
+import { parseAllDocuments } from "yaml";
+async function loadManifestFile(filePath, opts = {}) {
+  const absFile = path3.resolve(filePath);
+  let source;
+  try {
+    source = await fs3.readFile(absFile, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      throw new ManifestError(`Manifest file not found: ${absFile}`);
+    }
+    throw err;
+  }
+  const docs = parseAllDocuments(source, {
+    keepSourceTokens: true
+  });
+  const out = [];
+  let idx = 0;
+  for (const doc of docs) {
+    if (doc.errors.length && opts.throwOnParseError !== false) {
+      const e = doc.errors[0];
+      const pos = errorPosition(absFile, source, e);
+      throw new ManifestError(
+        `${pos.file}:${pos.line}:${pos.column}: YAML parse error: ${e.message}`
+      );
+    }
+    const data = doc.toJS({ maxAliasCount: -1 }) ?? {};
+    const kind = typeof data.kind === "string" ? data.kind : void 0;
+    const position = makePositionResolver(absFile, source, doc);
+    out.push({ file: absFile, docIndex: idx, kind, data, position });
+    idx++;
+  }
+  return out;
+}
+function errorPosition(file, source, e) {
+  if (Array.isArray(e.pos) && typeof e.pos[0] === "number") {
+    const { line, col } = offsetToLineCol(source, e.pos[0]);
+    return { file, line, column: col };
+  }
+  return { file, line: 1, column: 1 };
+}
+function offsetToLineCol(source, offset) {
+  let line = 1;
+  let col = 1;
+  for (let i = 0; i < offset && i < source.length; i++) {
+    if (source[i] === "\n") {
+      line++;
+      col = 1;
+    } else {
+      col++;
+    }
+  }
+  return { line, col };
+}
+function makePositionResolver(file, source, doc) {
+  return (jsonPath) => {
+    const keys = parseJsonPointer(jsonPath);
+    let node;
+    if (keys.length === 0) {
+      node = doc.contents;
+    } else {
+      node = doc.getIn(keys, true);
+      if (!node) {
+        for (let i = keys.length - 1; i >= 0; i--) {
+          const partial = keys.slice(0, i);
+          const candidate = doc.getIn(partial, true);
+          if (candidate) {
+            node = candidate;
+            break;
+          }
+        }
+      }
+    }
+    const range = node?.range;
+    if (range && typeof range[0] === "number") {
+      const { line, col } = offsetToLineCol(source, range[0]);
+      return { file, line, column: col };
+    }
+    return { file, line: 1, column: 1 };
+  };
+}
+function parseJsonPointer(pointer) {
+  if (!pointer) return [];
+  const trimmed = pointer.startsWith("/") ? pointer.slice(1) : pointer;
+  if (trimmed.length === 0) return [];
+  return trimmed.split("/").map((segment) => {
+    const decoded = segment.replace(/~1/g, "/").replace(/~0/g, "~");
+    const asNumber = Number(decoded);
+    return decoded !== "" && Number.isInteger(asNumber) && String(asNumber) === decoded ? asNumber : decoded;
+  });
+}
+
+// src/manifest/validator.ts
+import Ajv2020 from "ajv/dist/2020.js";
+import addFormats from "ajv-formats";
+
+// src/schema/qavor.defs.schema.json
+var qavor_defs_schema_default = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://qavor.dev/schemas/qavor.defs.schema.json",
+  title: "qavor shared definitions",
+  description: "Shared $defs referenced by every kind-specific qavor manifest schema. Has no top-level shape of its own; consume via $ref to /$defs/<name>.",
+  type: "object",
+  $defs: {
+    name: {
+      type: "string",
+      pattern: "^[a-z0-9][a-z0-9._-]{0,62}$",
+      description: "Lowercase identifier. Letters, digits, dot, dash, underscore. 1-63 chars. Used as service/stateful/profile/repo/group identifiers."
+    },
+    envKey: {
+      type: "string",
+      pattern: "^[A-Z_][A-Z0-9_]*$",
+      description: "Conventional UPPER_SNAKE_CASE environment variable name."
+    },
+    envScalar: {
+      description: "Scalar value usable on the right-hand side of an env entry. Strings support ${VAR} and ${secret:NAME} interpolation.",
+      oneOf: [
+        { type: "string" },
+        { type: "number" },
+        { type: "boolean" }
+      ]
+    },
+    envSpec: {
+      description: "Long-form env entry. Use when you need typing, validation, default vs override, secret marking, or documentation.",
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        value: { $ref: "#/$defs/envScalar" },
+        default: { $ref: "#/$defs/envScalar" },
+        required: { type: "boolean", default: false },
+        type: { type: "string", enum: ["string", "int", "number", "bool", "url", "duration"] },
+        pattern: { type: "string", format: "regex" },
+        secret: { type: "boolean", default: false },
+        description: { type: "string" }
+      }
+    },
+    envMap: {
+      description: "Map of env names to scalar values or long-form envSpec entries.",
+      type: "object",
+      patternProperties: {
+        "^[A-Z_][A-Z0-9_]*$": {
+          oneOf: [
+            { $ref: "#/$defs/envScalar" },
+            { $ref: "#/$defs/envSpec" }
+          ]
+        }
+      },
+      additionalProperties: false
+    },
+    envBlock: {
+      description: "Layered env block. `common` always applies; `native` or `docker` is layered on top depending on the active run mode. See the proposal section on Manifest Resolution Order for the full precedence chain.",
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        common: { $ref: "#/$defs/envMap" },
+        native: { $ref: "#/$defs/envMap" },
+        docker: { $ref: "#/$defs/envMap" }
+      }
+    },
+    statefulEnvBlock: {
+      description: "Env block for a stateful service. Adds `publish`: env vars exposed to dependents at start time.",
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        common: { $ref: "#/$defs/envMap" },
+        native: { $ref: "#/$defs/envMap" },
+        docker: { $ref: "#/$defs/envMap" },
+        publish: { $ref: "#/$defs/envMap" }
+      }
+    },
+    runtimeStep: {
+      description: "Single shell step in a runtime block (check_installed, install, prepare, run).",
+      type: "object",
+      additionalProperties: false,
+      required: ["cmd"],
+      properties: {
+        cmd: { type: "string", description: "Shell command. Multiline strings are treated as a script." },
+        cwd: { type: "string", description: "Working directory relative to the manifest file." },
+        env: { $ref: "#/$defs/envMap" },
+        shell: { type: "string", description: "Override shell. Defaults to `/bin/sh -c` (POSIX) or `cmd /C` on Windows." }
+      }
+    },
+    runtimeBackend: {
+      description: "Runtime backend definition. Each of `check_installed`, `install`, `prepare`, `run` is optional but ordered: install runs only when check_installed fails; prepare runs before run.",
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        enabled: { type: "boolean", default: false },
+        check_installed: { $ref: "#/$defs/runtimeStep" },
+        install: { $ref: "#/$defs/runtimeStep" },
+        prepare: { $ref: "#/$defs/runtimeStep" },
+        run: { $ref: "#/$defs/runtimeStep" }
+      }
+    },
+    runtimeBlock: {
+      description: "Available runtime backends. A service or stateful manifest may declare any subset; the active backend is chosen by the resolved `mode`.",
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        native: { $ref: "#/$defs/runtimeBackend" },
+        docker: { $ref: "#/$defs/runtimeBackend" },
+        "docker-compose": { $ref: "#/$defs/runtimeBackend" }
+      }
+    },
+    mode: {
+      description: "Run mode. `docker-compose` is only valid for stateful manifests at v0.",
+      type: "string",
+      enum: ["native", "docker", "docker-compose"]
+    },
+    profileRef: {
+      description: "Reference to a profile by name. Profiles are merged in declaration order; later entries win.",
+      $ref: "#/$defs/name"
+    },
+    requirement: {
+      description: "A single dependency edge. Exactly one of `service`, `stateful`, or `group` must be set.",
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        service: { type: "string", description: "Service reference. `<service>` for same-workspace, `<repo>:<service>` permitted." },
+        stateful: { $ref: "#/$defs/name" },
+        group: { $ref: "#/$defs/name" },
+        optional: { type: "boolean", default: false },
+        condition: {
+          type: "string",
+          description: "Optional gating expression. Examples: `mode == 'docker'`, `profile == 'dev'`, `os == 'darwin'`."
+        },
+        waitFor: {
+          type: "string",
+          enum: ["start", "ready"],
+          default: "ready",
+          description: "Whether to wait for process-up or for the readiness probe to pass before starting dependents."
+        }
+      },
+      oneOf: [
+        { required: ["service"] },
+        { required: ["stateful"] },
+        { required: ["group"] }
+      ]
+    },
+    hookCommands: {
+      description: "One or more shell commands or paths to executable scripts, run in the manifest's directory.",
+      oneOf: [
+        { type: "string" },
+        { type: "array", items: { type: "string" }, minItems: 1 }
+      ]
+    },
+    hooks: {
+      description: "Lifecycle hooks. Each hook list runs in the manifest's directory at the corresponding lifecycle event.",
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        pre_clone: { $ref: "#/$defs/hookCommands" },
+        post_clone: { $ref: "#/$defs/hookCommands" },
+        pre_prepare: { $ref: "#/$defs/hookCommands" },
+        post_prepare: { $ref: "#/$defs/hookCommands" },
+        pre_run: { $ref: "#/$defs/hookCommands" },
+        post_run: { $ref: "#/$defs/hookCommands" },
+        pre_stop: { $ref: "#/$defs/hookCommands" },
+        post_stop: { $ref: "#/$defs/hookCommands" }
+      }
+    },
+    schemaVersion: {
+      description: "Manifest schema version. Defaults to 1 if omitted.",
+      type: "integer",
+      enum: [1]
+    }
+  }
+};
+
+// src/schema/qavor.workspaces.schema.json
+var qavor_workspaces_schema_default = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://qavor.dev/schemas/qavor.workspaces.schema.json",
+  title: "qavor workspaces manifest",
+  description: "Workspace pointer file. Lives at the root of the workspace directory as `qavor.yaml` and is created automatically by `qavor init`. Its only job is to point at the project repo whose `kind: project` manifest enumerates the rest of the workspace.",
+  type: "object",
+  additionalProperties: false,
+  required: ["kind", "root_project_path"],
+  properties: {
+    kind: { const: "workspaces" },
+    schemaVersion: { $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/schemaVersion" },
+    root_project_path: {
+      type: "string",
+      description: "Workspace-relative path to the directory containing the project repo's `qavor.yaml` (kind: project)."
+    }
+  }
+};
+
+// src/schema/qavor.project.schema.json
+var qavor_project_schema_default = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://qavor.dev/schemas/qavor.project.schema.json",
+  title: "qavor project manifest",
+  description: "Project-level manifest. Lives at the root of the project repo as `qavor.yaml`. Defines workspace identity and enumerates the repos that make up the workspace.",
+  type: "object",
+  additionalProperties: false,
+  required: ["kind", "name", "repositories"],
+  properties: {
+    kind: { const: "project" },
+    schemaVersion: { $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/schemaVersion" },
+    name: {
+      $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/name",
+      description: "Human-readable workspace name. Used as the compose project namespace and the on-disk workspace identifier."
+    },
+    description: { type: "string" },
+    git: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        root_url: {
+          type: "string",
+          description: "Base git URL for repos in this project. Combined with `repo_prefix` and a repo `name` to derive the clone URL when no explicit `url` is given."
+        },
+        repo_prefix: {
+          type: "string",
+          description: "Optional prefix prepended to repo names when deriving clone URLs."
+        },
+        default_branch: {
+          type: "string",
+          default: "main",
+          description: "Default branch used when a repo entry does not pin its own."
+        },
+        remote: {
+          type: "string",
+          enum: ["ssh", "https"],
+          description: "Hint for clone URL form when `root_url` is a host instead of a full URL."
+        },
+        shallow: { type: "boolean", default: false },
+        submodules: { type: "boolean", default: false }
+      }
+    },
+    groups: {
+      description: "Named groups of repo names. A repo may appear in multiple groups. Repos can also self-declare additional group memberships in their own `kind: repo` or service/stateful manifests.",
+      type: "object",
+      patternProperties: {
+        "^[a-z0-9][a-z0-9._-]{0,62}$": {
+          type: "array",
+          items: { $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/name" },
+          uniqueItems: true,
+          minItems: 1
+        }
+      },
+      additionalProperties: false
+    },
+    repositories: {
+      description: "Repos that compose the workspace. Each entry is either a bare name (URL derived from `git.root_url` + `git.repo_prefix` + name) or an object with explicit fields.",
+      type: "array",
+      minItems: 1,
+      items: {
+        oneOf: [
+          { $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/name" },
+          { $ref: "#/$defs/repoEntry" }
+        ]
+      }
+    }
+  },
+  $defs: {
+    repoEntry: {
+      type: "object",
+      additionalProperties: false,
+      required: ["name"],
+      properties: {
+        name: { $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/name" },
+        url: {
+          type: "string",
+          description: "Explicit git URL. Overrides URL derivation from `git.root_url` + `git.repo_prefix`."
+        },
+        branch: { type: "string" },
+        tag: { type: "string" },
+        commit: {
+          type: "string",
+          pattern: "^[0-9a-f]{7,40}$"
+        },
+        path: {
+          type: "string",
+          description: "Workspace-relative clone path. Defaults to `./<name>` (or `./<name>.git` to match the conventional layout)."
+        },
+        groups: {
+          type: "array",
+          items: { $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/name" },
+          uniqueItems: true,
+          description: "Inline group memberships in addition to the top-level `groups` map."
+        },
+        shallow: { type: "boolean" },
+        submodules: { type: "boolean" },
+        optional: {
+          type: "boolean",
+          default: false,
+          description: "Skip rather than fail if cloning is not authorized."
+        }
+      },
+      allOf: [
+        {
+          description: "At most one of branch, tag, or commit may be set.",
+          not: {
+            anyOf: [
+              { required: ["branch", "tag"] },
+              { required: ["branch", "commit"] },
+              { required: ["tag", "commit"] }
+            ]
+          }
+        }
+      ]
+    }
+  }
+};
+
+// src/schema/qavor.repo.schema.json
+var qavor_repo_schema_default = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://qavor.dev/schemas/qavor.repo.schema.json",
+  title: "qavor repo manifest",
+  description: "Per-repo metadata. Lives at the root of an individual repo as `qavor.yaml` (or as one document of a multi-document `qavor.yaml`). Carries information that is not specific to a single service: identity, group membership, and lifecycle hooks that fire around qavor verbs at the repo level.",
+  type: "object",
+  additionalProperties: false,
+  required: ["kind", "name"],
+  properties: {
+    kind: { const: "repo" },
+    schemaVersion: { $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/schemaVersion" },
+    name: {
+      $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/name",
+      description: "Repository identifier. Must match the `name` used in the project manifest's `repositories` list."
+    },
+    description: { type: "string" },
+    groups: {
+      type: "array",
+      items: { $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/name" },
+      uniqueItems: true,
+      description: "Additional group memberships, layered on top of any groups assigned by the project manifest."
+    },
+    hooks: { $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/hooks" }
+  }
+};
+
+// src/schema/qavor.service.schema.json
+var qavor_service_schema_default = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://qavor.dev/schemas/qavor.service.schema.json",
+  title: "qavor service manifest",
+  description: "Runnable application. Lives at the root of a single-service repo as `qavor.yaml`, or under a sub-directory of a multi-service repo (e.g. `service-foo/qavor.yaml`). When this manifest is at the root of a repo, its `groups` also define repo-level group membership.",
+  type: "object",
+  additionalProperties: false,
+  required: ["kind", "name"],
+  properties: {
+    kind: { const: "service" },
+    schemaVersion: { $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/schemaVersion" },
+    name: {
+      $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/name",
+      description: "Service identifier. Must be unique within the workspace; cross-repo references use this name."
+    },
+    description: { type: "string" },
+    groups: {
+      type: "array",
+      items: { $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/name" },
+      uniqueItems: true,
+      description: "Additional group memberships. When this manifest is at the root of a repo, these also define repo group membership."
+    },
+    profiles: {
+      type: "array",
+      items: { $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/profileRef" },
+      uniqueItems: true,
+      description: "Profiles applied to this service in declaration order. Profile values are layered first; this manifest's own `runtime` and `env` are merged on top."
+    },
+    runtime: {
+      $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/runtimeBlock",
+      description: "Available runtime backends. Services typically declare `native` and/or `docker`. `docker-compose` is reserved for stateful manifests at v0."
+    },
+    mode: {
+      description: "Default run mode for this service. Overridable per invocation via `--mode`. Must match a backend whose `enabled: true` is set on this service or one of its profiles.",
+      type: "string",
+      enum: ["native", "docker"]
+    },
+    require: {
+      type: "array",
+      items: { $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/requirement" },
+      description: "Dependencies that must be running before this service starts."
+    },
+    env: { $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/envBlock" },
+    hooks: { $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/hooks" }
+  }
+};
+
+// src/schema/qavor.stateful.schema.json
+var qavor_stateful_schema_default = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://qavor.dev/schemas/qavor.stateful.schema.json",
+  title: "qavor stateful service manifest",
+  description: "Externally provided stateful service (postgres, kafka, redis, ...). Lives at the root of a stateful-dep repo as `qavor.yaml`, or under a sub-directory of a deps repo (e.g. `postgresql/qavor.yaml`). At v0 stateful services run via `docker-compose` and qavor owns the generated compose project (per ADR-005).",
+  type: "object",
+  additionalProperties: false,
+  required: ["kind", "name"],
+  properties: {
+    kind: { const: "stateful" },
+    schemaVersion: { $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/schemaVersion" },
+    name: {
+      $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/name",
+      description: "Stateful service identifier. Must be unique within the workspace."
+    },
+    description: { type: "string" },
+    groups: {
+      type: "array",
+      items: { $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/name" },
+      uniqueItems: true,
+      description: "Additional group memberships. When this manifest is at the root of a repo, these also define repo group membership."
+    },
+    profiles: {
+      type: "array",
+      items: { $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/profileRef" },
+      uniqueItems: true
+    },
+    runtime: {
+      $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/runtimeBlock",
+      description: "Available runtime backends. v0 stateful services delegate to `docker-compose`; `native` and `docker` are reserved for future use."
+    },
+    mode: {
+      description: "Default run mode. v0 stateful services should use `docker-compose`.",
+      type: "string",
+      enum: ["docker-compose", "native", "docker"],
+      default: "docker-compose"
+    },
+    require: {
+      type: "array",
+      items: { $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/requirement" }
+    },
+    env: {
+      $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/statefulEnvBlock",
+      description: "Layered env block. `publish` is the explicit contract exposed to dependents at start time; values are interpolated against the resolved env of this stateful service."
+    },
+    hooks: { $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/hooks" }
+  }
+};
+
+// src/schema/qavor.profile.schema.json
+var qavor_profile_schema_default = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://qavor.dev/schemas/qavor.profile.schema.json",
+  title: "qavor profile manifest",
+  description: "Reusable runtime + env bundle. Referenced by services and stateful manifests via the `profiles:` list. Profiles can themselves reference other profiles; resolution flattens the chain in declaration order with later entries winning. A profile's runtime/env layer below the referencing manifest's own runtime/env.",
+  type: "object",
+  additionalProperties: false,
+  required: ["kind", "name"],
+  properties: {
+    kind: { const: "profile" },
+    schemaVersion: { $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/schemaVersion" },
+    name: {
+      $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/name",
+      description: "Profile identifier. Referenced from `profiles:` lists and from CLI flags."
+    },
+    description: { type: "string" },
+    profiles: {
+      type: "array",
+      items: { $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/profileRef" },
+      uniqueItems: true,
+      description: "Other profiles this one extends. Resolved in declaration order before this profile's own values are applied."
+    },
+    runtime: { $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/runtimeBlock" },
+    mode: {
+      type: "string",
+      enum: ["native", "docker", "docker-compose"]
+    },
+    env: { $ref: "https://qavor.dev/schemas/qavor.defs.schema.json#/$defs/envBlock" }
+  }
+};
+
+// src/manifest/validator.ts
+var KIND_SCHEMA_IDS = {
+  workspaces: qavor_workspaces_schema_default.$id,
+  project: qavor_project_schema_default.$id,
+  repo: qavor_repo_schema_default.$id,
+  service: qavor_service_schema_default.$id,
+  stateful: qavor_stateful_schema_default.$id,
+  profile: qavor_profile_schema_default.$id
+};
+var ALL_KINDS = [
+  "workspaces",
+  "project",
+  "repo",
+  "service",
+  "stateful",
+  "profile"
+];
+var ajvSingleton = null;
+var validatorCache = /* @__PURE__ */ new Map();
+function getAjv() {
+  if (ajvSingleton) return ajvSingleton;
+  const ajv = new Ajv2020({
+    allErrors: true,
+    strict: false,
+    allowUnionTypes: true
+  });
+  addFormats(ajv);
+  ajv.addSchema(qavor_defs_schema_default);
+  ajv.addSchema(qavor_workspaces_schema_default);
+  ajv.addSchema(qavor_project_schema_default);
+  ajv.addSchema(qavor_repo_schema_default);
+  ajv.addSchema(qavor_service_schema_default);
+  ajv.addSchema(qavor_stateful_schema_default);
+  ajv.addSchema(qavor_profile_schema_default);
+  ajvSingleton = ajv;
+  return ajv;
+}
+function getValidator(kind) {
+  const cached = validatorCache.get(kind);
+  if (cached) return cached;
+  const ajv = getAjv();
+  const id = KIND_SCHEMA_IDS[kind];
+  const fn = ajv.getSchema(id);
+  if (!fn) throw new Error(`Internal: schema not registered for kind=${kind}`);
+  validatorCache.set(kind, fn);
+  return fn;
+}
+function isKnownKind(value) {
+  return typeof value === "string" && ALL_KINDS.includes(value);
+}
+function validateDocument(doc) {
+  const issues = [];
+  if (!doc.kind) {
+    const pos = doc.position("");
+    issues.push({
+      file: pos.file,
+      line: pos.line,
+      column: pos.column,
+      kind: "unknown",
+      path: "",
+      message: "Missing top-level `kind:` field."
+    });
+    return { ok: false, issues };
+  }
+  if (!isKnownKind(doc.kind)) {
+    const pos = doc.position("/kind");
+    issues.push({
+      file: pos.file,
+      line: pos.line,
+      column: pos.column,
+      kind: String(doc.kind),
+      path: "/kind",
+      message: `Unknown kind: ${doc.kind}. Expected one of: ${ALL_KINDS.join(", ")}`
+    });
+    return { ok: false, issues };
+  }
+  const validator = getValidator(doc.kind);
+  const valid = validator(doc.data);
+  if (valid) return { ok: true, issues: [] };
+  for (const err of validator.errors ?? []) {
+    issues.push(formatAjvError(doc, err));
+  }
+  return { ok: false, issues };
+}
+function formatAjvError(doc, err) {
+  const instancePath = err.instancePath ?? "";
+  const pos = doc.position(instancePath);
+  const where = instancePath || "<root>";
+  let message = err.message ?? "invalid";
+  if (err.keyword === "additionalProperties" && err.params && typeof err.params.additionalProperty === "string") {
+    const extra = err.params.additionalProperty;
+    message = `Unexpected property '${extra}'`;
+  } else if (err.keyword === "required" && err.params && typeof err.params.missingProperty === "string") {
+    const missing = err.params.missingProperty;
+    message = `Missing required property '${missing}'`;
+  } else if (err.keyword === "enum" && err.params && Array.isArray(err.params.allowedValues)) {
+    const allowed = err.params.allowedValues;
+    message = `${message}: ${allowed.map((v) => JSON.stringify(v)).join(", ")}`;
+  } else if (err.keyword === "pattern" && err.params && typeof err.params.pattern === "string") {
+    message = `Value does not match pattern /${err.params.pattern}/`;
+  }
+  return {
+    file: pos.file,
+    line: pos.line,
+    column: pos.column,
+    kind: String(doc.kind ?? "unknown"),
+    path: where,
+    message
+  };
+}
+function formatIssue(i) {
+  return `${i.file}:${i.line}:${i.column} [${i.kind}] ${i.path}: ${i.message}`;
+}
+
+// src/workspace/paths.ts
+import path4 from "path";
+function workspacePaths(root) {
+  const abs = path4.resolve(root);
+  const stateRoot = path4.join(abs, ".qavor");
+  return {
+    root: abs,
+    workspacesFile: path4.join(abs, "qavor.yaml"),
+    stateRoot,
+    stateDir: path4.join(stateRoot, "state"),
+    logsDir: path4.join(stateRoot, "logs"),
+    composeDir: path4.join(stateRoot, "compose"),
+    cacheDir: path4.join(stateRoot, "cache"),
+    workspaceMetaFile: path4.join(stateRoot, "workspace.json"),
+    stateGitignore: path4.join(stateRoot, ".gitignore")
+  };
+}
+
+// src/workspace/init.ts
+var URL_RE = /^(?:git@[^:]+:|https?:\/\/|git:\/\/|ssh:\/\/|file:\/\/)/;
+function looksLikeGitUrl(s) {
+  return URL_RE.test(s);
+}
+function projectRepoNameFromUrl(url) {
+  const cleaned = url.replace(/[?#].*$/, "");
+  const last = cleaned.split("/").pop() ?? cleaned.split(":").pop() ?? "project";
+  return last.replace(/\.git$/, "");
+}
+async function initWorkspace(opts) {
+  const workspaceRoot = path5.resolve(opts.into ?? process.cwd());
+  await ensureDir(workspaceRoot);
+  const paths = workspacePaths(workspaceRoot);
+  let projectRepoPath;
+  let cloned = false;
+  if (looksLikeGitUrl(opts.source)) {
+    const repoName = projectRepoNameFromUrl(opts.source);
+    const target = path5.join(workspaceRoot, `${repoName}.git`);
+    if (await isDirectory(target)) {
+      if (!await isGitRepo(target)) {
+        throw new UserError(
+          `Cannot reuse ${target}: directory exists but is not a git repo. Move it aside and re-run.`
+        );
+      }
+      opts.logger.info({ target }, "reusing existing project repo clone");
+      projectRepoPath = target;
+    } else {
+      const cacheDir = path5.join(globalCacheDir(), "projects", urlHash(opts.source));
+      await ensureDir(path5.dirname(cacheDir));
+      opts.logger.info({ url: opts.source, target }, "cloning project repo");
+      await gitClone({ url: opts.source, dest: target });
+      try {
+        await ensureDir(cacheDir);
+        await fs4.writeFile(
+          path5.join(cacheDir, "source.json"),
+          JSON.stringify({ url: opts.source, cloned_to: target, at: (/* @__PURE__ */ new Date()).toISOString() }, null, 2)
+        );
+      } catch {
+      }
+      projectRepoPath = target;
+      cloned = true;
+    }
+  } else {
+    const localPath = path5.resolve(opts.source);
+    if (!await isDirectory(localPath)) {
+      throw new UserError(`Project repo source does not exist or is not a directory: ${localPath}`);
+    }
+    projectRepoPath = localPath;
+  }
+  const projectManifestFile = path5.join(projectRepoPath, "qavor.yaml");
+  const docs = await loadManifestFile(projectManifestFile);
+  const projectDoc = docs.find((d) => d.kind === "project");
+  if (!projectDoc) {
+    throw new ManifestError(
+      `Project repo at ${projectRepoPath} is missing a \`kind: project\` document in qavor.yaml.`
+    );
+  }
+  const result = validateDocument(projectDoc);
+  if (!result.ok) {
+    const msg = result.issues.map((i) => `  ${i.file}:${i.line}:${i.column} ${i.path}: ${i.message}`).join("\n");
+    throw new ManifestError(`Invalid project manifest:
+${msg}`);
+  }
+  const project = projectDoc.data;
+  await ensureDir(paths.stateRoot);
+  await ensureDir(paths.stateDir);
+  await ensureDir(paths.logsDir);
+  await ensureDir(paths.composeDir);
+  await ensureDir(paths.cacheDir);
+  await fs4.writeFile(
+    paths.stateGitignore,
+    [
+      "# qavor state directory \u2014 all files are generated. Do not commit.",
+      "*",
+      "!.gitignore",
+      ""
+    ].join("\n")
+  );
+  const relProjectPath = "./" + path5.relative(workspaceRoot, projectRepoPath).split(path5.sep).join("/");
+  const workspacesYaml = renderWorkspacesYaml(relProjectPath);
+  await fs4.writeFile(paths.workspacesFile, workspacesYaml, "utf8");
+  const manifestHash = createHash2("sha256").update(await fs4.readFile(projectManifestFile)).digest("hex");
+  await writeJsonFile(paths.workspaceMetaFile, {
+    project_name: project.name,
+    project_repo_path: projectRepoPath,
+    manifest_hash: manifestHash,
+    initialized_at: (/* @__PURE__ */ new Date()).toISOString()
+  });
+  return { paths, projectRepoPath, project, cloned };
+}
+function urlHash(url) {
+  return createHash2("sha256").update(url).digest("hex").slice(0, 16);
+}
+function renderWorkspacesYaml(relProjectPath) {
+  return [
+    "# Generated by `qavor init`. Points at the project repo whose",
+    "# `kind: project` manifest enumerates the rest of the workspace.",
+    "kind: workspaces",
+    `root_project_path: ${relProjectPath}`,
+    ""
+  ].join("\n");
+}
+
+// src/cli/options.ts
+function rootOptions(cmd) {
+  const opts = cmd.opts();
+  return {
+    json: Boolean(opts.json),
+    verbose: Boolean(opts.verbose),
+    jobs: typeof opts.jobs === "string" ? Number.parseInt(opts.jobs, 10) : void 0,
+    config: typeof opts.config === "string" ? opts.config : void 0
+  };
+}
+function inheritRootOptions(cmd) {
+  let current = cmd;
+  while (current && current.parent) current = current.parent;
+  if (!current) return { json: false, verbose: false, jobs: void 0, config: void 0 };
+  return rootOptions(current);
+}
+
+// src/cli/commands/init.ts
+function registerInit(program) {
+  program.command("init").description("Bootstrap a workspace from a project repo (local path or git URL).").argument("<source>", "Local path to a project repo, or a git URL.").option("--into <dir>", "Workspace root directory. Defaults to the current directory.").action(async (source, opts, cmd) => {
+    const root = inheritRootOptions(cmd);
+    const logger = getLogger();
+    const initOpts = { source, logger };
+    if (opts.into) initOpts.into = opts.into;
+    const result = await initWorkspace(initOpts);
+    if (root.json) {
+      emitJson({
+        ok: true,
+        workspace: result.paths.root,
+        project_name: result.project.name,
+        project_repo_path: result.projectRepoPath,
+        cloned_project: result.cloned,
+        repositories: result.project.repositories.length
+      });
+    } else {
+      emit(`Workspace initialized at ${result.paths.root}`);
+      emit(`  project: ${result.project.name}`);
+      emit(`  project repo: ${path6.relative(result.paths.root, result.projectRepoPath)}`);
+      emit(`  repositories declared: ${result.project.repositories.length}`);
+      emit(`  next: qavor clone`);
+    }
+  });
+}
+
+// src/cli/commands/workspace.ts
+import path8 from "path";
+import fs6 from "fs/promises";
+
+// src/workspace/locate.ts
+import fs5 from "fs/promises";
+import path7 from "path";
+async function findWorkspaceRoot(start) {
+  let cur = path7.resolve(start);
+  for (let i = 0; i < 64; i++) {
+    const candidate = path7.join(cur, "qavor.yaml");
+    if (await isFile(candidate)) {
+      try {
+        const docs = await loadManifestFile(candidate, { throwOnParseError: false });
+        if (docs.some((d) => d.kind === "workspaces")) return cur;
+      } catch {
+      }
+    }
+    const parent = path7.dirname(cur);
+    if (parent === cur) return null;
+    cur = parent;
+  }
+  return null;
+}
+async function resolveWorkspace(start = process.cwd()) {
+  const root = await findWorkspaceRoot(start);
+  if (!root) {
+    throw new UserError(
+      `No qavor workspace found searching upward from ${start}. Run \`qavor init <project-repo-source>\` first.`
+    );
+  }
+  const paths = workspacePaths(root);
+  const docs = await loadManifestFile(paths.workspacesFile);
+  const workspaceDoc = docs.find((d) => d.kind === "workspaces");
+  if (!workspaceDoc) {
+    throw new UserError(`Workspace pointer at ${paths.workspacesFile} has no \`kind: workspaces\` document.`);
+  }
+  const rootProjectPath = workspaceDoc.data.root_project_path;
+  if (typeof rootProjectPath !== "string" || rootProjectPath.length === 0) {
+    throw new UserError(
+      `Workspace pointer at ${paths.workspacesFile} is missing \`root_project_path\`.`
+    );
+  }
+  const projectRepoPath = path7.isAbsolute(rootProjectPath) ? rootProjectPath : path7.resolve(paths.root, rootProjectPath);
+  const projectManifestFile = path7.join(projectRepoPath, "qavor.yaml");
+  return { paths, projectRepoPath, projectManifestFile };
+}
+async function readProjectManifest(projectManifestFile) {
+  const docs = await loadManifestFile(projectManifestFile);
+  const project = docs.find((d) => d.kind === "project");
+  if (!project) {
+    throw new UserError(`No \`kind: project\` document found in ${projectManifestFile}.`);
+  }
+  return { data: project.data };
+}
+
+// src/cli/commands/workspace.ts
+function registerWorkspace(program) {
+  const ws = program.command("workspace").description("Workspace operations.");
+  ws.command("info").description("Show information about the workspace at or above the cwd.").action(async (_opts, cmd) => {
+    const root = inheritRootOptions(cmd);
+    const resolved = await resolveWorkspace();
+    const project = await readProjectManifest(resolved.projectManifestFile);
+    let meta = {};
+    try {
+      meta = await readJsonFile(resolved.paths.workspaceMetaFile);
+    } catch {
+    }
+    const info = {
+      workspace_root: resolved.paths.root,
+      workspaces_file: resolved.paths.workspacesFile,
+      project_repo_path: resolved.projectRepoPath,
+      project_manifest_file: resolved.projectManifestFile,
+      project_name: typeof project.data.name === "string" ? project.data.name : null,
+      state_dir: resolved.paths.stateRoot,
+      meta
+    };
+    if (root.json) {
+      emitJson(info);
+      return;
+    }
+    emit(`Workspace root:        ${info.workspace_root}`);
+    emit(`Workspaces manifest:   ${path8.relative(info.workspace_root, info.workspaces_file)}`);
+    emit(`Project repo path:     ${path8.relative(info.workspace_root, info.project_repo_path)}`);
+    emit(`Project manifest:      ${path8.relative(info.workspace_root, info.project_manifest_file)}`);
+    emit(`Project name:          ${info.project_name ?? "<unknown>"}`);
+    emit(`State directory:       ${path8.relative(info.workspace_root, info.state_dir)}`);
+    if (Object.keys(meta).length > 0) {
+      emit("Workspace meta:");
+      for (const [k, v] of Object.entries(meta)) emit(`  ${k}: ${typeof v === "string" ? v : JSON.stringify(v)}`);
+    }
+    try {
+      await fs6.access(resolved.paths.workspaceMetaFile);
+    } catch {
+    }
+  });
+}
+
+// src/cli/commands/validate.ts
+import path9 from "path";
+import fs7 from "fs/promises";
+import pMap from "p-map";
+
+// src/util/concurrency.ts
+import os from "os";
+import pLimit from "p-limit";
+function resolveJobs(override) {
+  if (typeof override === "number" && Number.isFinite(override) && override >= 1) {
+    return Math.floor(override);
+  }
+  const avail = typeof os.availableParallelism === "function" ? os.availableParallelism() : os.cpus().length;
+  return Math.max(1, avail);
+}
+
+// src/cli/commands/validate.ts
+function registerValidate(program) {
+  program.command("validate").description("Validate one or more qavor manifest files. Targets a file or a directory.").argument("<path>", "Path to a qavor.yaml file, a directory containing one, or a directory of multiple manifests.").action(async (target, _opts, cmd) => {
+    const root = inheritRootOptions(cmd);
+    const logger = getLogger();
+    const abs = path9.resolve(target);
+    const files = [];
+    if (await isFile(abs)) {
+      files.push(abs);
+    } else if (await isDirectory(abs)) {
+      const direct = path9.join(abs, "qavor.yaml");
+      if (await isFile(direct)) files.push(direct);
+      try {
+        const entries = await fs7.readdir(abs, { withFileTypes: true });
+        for (const e of entries) {
+          if (e.isDirectory()) {
+            const child = path9.join(abs, e.name, "qavor.yaml");
+            if (await isFile(child)) files.push(child);
+          }
+          if (e.isFile() && e.name === "qavor.yaml") {
+          }
+        }
+      } catch {
+      }
+    } else {
+      throw new UserError(`Path not found: ${abs}`);
+    }
+    if (files.length === 0) throw new UserError(`No qavor.yaml files found under ${abs}.`);
+    const jobs = resolveJobs(root.jobs);
+    const issues = [];
+    await pMap(
+      files,
+      async (file) => {
+        try {
+          const docs = await loadManifestFile(file);
+          for (const d of docs) {
+            const r = validateDocument(d);
+            if (!r.ok) issues.push(...r.issues);
+          }
+        } catch (err) {
+          issues.push({
+            file,
+            line: 1,
+            column: 1,
+            kind: "unknown",
+            path: "",
+            message: err instanceof Error ? err.message : String(err)
+          });
+        }
+      },
+      { concurrency: jobs }
+    );
+    if (root.json) {
+      emitJson({ ok: issues.length === 0, files: files.length, issues });
+    } else {
+      if (issues.length === 0) {
+        emit(`OK \u2014 ${files.length} file(s) validated.`);
+      } else {
+        emit(`FAILED \u2014 ${issues.length} issue(s) across ${files.length} file(s):`);
+        for (const i of issues) emit(`  ${formatIssue(i)}`);
+      }
+    }
+    if (issues.length > 0) {
+      logger.debug({ count: issues.length }, "validation failed");
+      throw new ManifestError(`Validation failed with ${issues.length} issue(s).`);
+    }
+  });
+}
+
+// src/cli/commands/git.ts
+import path11 from "path";
+import pMap2 from "p-map";
+
+// src/workspace/repos.ts
+import path10 from "path";
+function resolveRepos(opts) {
+  const list = opts.project.repositories;
+  const repos = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const entry of list) {
+    const normalized = typeof entry === "string" ? { name: entry } : entry;
+    const name = normalized.name;
+    if (!name) throw new ManifestError(`Project repository entry is missing a name.`);
+    if (seen.has(name)) {
+      throw new ManifestError(`Duplicate repository name in project manifest: '${name}'.`);
+    }
+    seen.add(name);
+    const dir = normalized.path ? path10.isAbsolute(normalized.path) ? normalized.path : path10.resolve(opts.workspaceRoot, normalized.path) : path10.join(opts.workspaceRoot, `${name}.git`);
+    const url = deriveCloneUrl({
+      explicitUrl: normalized.url,
+      rootUrl: opts.project.git?.root_url,
+      repoPrefix: opts.project.git?.repo_prefix,
+      name
+    });
+    repos.push({
+      name,
+      url,
+      dir,
+      branch: normalized.branch ?? opts.project.git?.default_branch,
+      tag: normalized.tag,
+      commit: normalized.commit,
+      shallow: normalized.shallow ?? opts.project.git?.shallow,
+      submodules: normalized.submodules ?? opts.project.git?.submodules,
+      optional: Boolean(normalized.optional),
+      isProjectRepo: path10.resolve(dir) === path10.resolve(opts.projectRepoPath)
+    });
+  }
+  return repos;
+}
+
+// src/cli/repos.ts
+function selectRepos(all, selector) {
+  if (!selector || selector.length === 0) return all;
+  const set = new Set(selector);
+  const out = [];
+  for (const r of all) {
+    if (set.has(r.name)) {
+      out.push(r);
+      set.delete(r.name);
+    }
+  }
+  if (set.size > 0) {
+    throw new Error(
+      `Unknown repo${set.size > 1 ? "s" : ""}: ${[...set].join(", ")}`
+    );
+  }
+  return out;
+}
+async function reposPresent(repos) {
+  const out = [];
+  for (const r of repos) {
+    if (await isDirectory(r.dir)) out.push(r);
+  }
+  return out;
+}
+
+// src/cli/commands/git.ts
+async function loadProjectRepos() {
+  const ws = await resolveWorkspace();
+  const project = await readProjectManifest(ws.projectManifestFile);
+  const repos = resolveRepos({
+    workspaceRoot: ws.paths.root,
+    project: project.data,
+    projectRepoPath: ws.projectRepoPath
+  });
+  return { workspaceRoot: ws.paths.root, repos };
+}
+function repoOption(c) {
+  return c.option("--repo <name...>", "Operate on a subset of repos by name.");
+}
+function registerGitCommands(program) {
+  repoOption(
+    program.command("clone").description("Clone every repo enumerated in the project manifest.")
+  ).action(async (opts, cmd) => {
+    const root = inheritRootOptions(cmd);
+    const logger = getLogger();
+    const { workspaceRoot, repos } = await loadProjectRepos();
+    const selected = selectRepos(repos, opts.repo);
+    const jobs = resolveJobs(root.jobs);
+    const results = [];
+    await pMap2(
+      selected,
+      async (r) => {
+        if (r.isProjectRepo) {
+          results.push({ repo: r.name, status: "present", message: "project repo (already cloned)" });
+          return;
+        }
+        if (await isGitRepo(r.dir)) {
+          results.push({ repo: r.name, status: "present" });
+          return;
+        }
+        try {
+          logger.info({ repo: r.name, url: r.url, dir: r.dir }, "clone: starting");
+          await gitClone({
+            url: r.url,
+            dest: r.dir,
+            branch: r.branch,
+            tag: r.tag,
+            commit: r.commit,
+            shallow: r.shallow,
+            submodules: r.submodules
+          });
+          results.push({ repo: r.name, status: "cloned" });
+        } catch (err) {
+          if (r.optional) {
+            results.push({ repo: r.name, status: "skipped", message: "optional; clone failed" });
+          } else {
+            throw new RuntimeFailure(
+              `Clone failed for ${r.name}: ${err instanceof Error ? err.message : String(err)}`
+            );
+          }
+        }
+      },
+      { concurrency: jobs }
+    );
+    if (root.json) {
+      emitJson({ workspace: workspaceRoot, results });
+      return;
+    }
+    for (const r of results) {
+      emit(`${r.status.padEnd(8)} ${r.repo}${r.message ? "  \u2014 " + r.message : ""}`);
+    }
+  });
+  repoOption(
+    program.command("sync").description("Run `git fetch && git pull --ff-only` across selected repos.")
+  ).action(async (opts, cmd) => {
+    const root = inheritRootOptions(cmd);
+    const { repos } = await loadProjectRepos();
+    const selected = await reposPresent(selectRepos(repos, opts.repo));
+    const jobs = resolveJobs(root.jobs);
+    const results = [];
+    await pMap2(
+      selected,
+      async (r) => {
+        try {
+          await gitFetch(r.dir);
+          await gitPullFastForward(r.dir);
+          results.push({ repo: r.name, ok: true });
+        } catch (err) {
+          results.push({ repo: r.name, ok: false, error: err instanceof Error ? err.message : String(err) });
+        }
+      },
+      { concurrency: jobs }
+    );
+    if (root.json) {
+      emitJson({ results });
+      return;
+    }
+    for (const r of results) emit(`${r.ok ? "ok  " : "fail"} ${r.repo}${r.error ? "  \u2014 " + r.error : ""}`);
+    if (results.some((r) => !r.ok)) throw new RuntimeFailure("Some repos failed to sync.");
+  });
+  repoOption(
+    program.command("status").description("Aggregated repo status across selected repos.")
+  ).action(async (opts, cmd) => {
+    const root = inheritRootOptions(cmd);
+    const { workspaceRoot, repos } = await loadProjectRepos();
+    const selected = await reposPresent(selectRepos(repos, opts.repo));
+    const jobs = resolveJobs(root.jobs);
+    const rows = await pMap2(
+      selected,
+      async (r) => {
+        const s = await readRepoStatus(r.dir);
+        return {
+          repo: r.name,
+          branch: s.branch,
+          ahead: s.ahead,
+          behind: s.behind,
+          dirty: s.dirtyCount,
+          last_commit: s.lastCommit,
+          last_commit_subject: s.lastCommitSubject
+        };
+      },
+      { concurrency: jobs }
+    );
+    if (root.json) {
+      emitJson({ workspace: workspaceRoot, repos: rows });
+      return;
+    }
+    const headers = ["REPO", "BRANCH", "AHEAD", "BEHIND", "DIRTY", "COMMIT", "SUBJECT"];
+    const data = rows.map((r) => [
+      r.repo,
+      r.branch ?? "-",
+      String(r.ahead),
+      String(r.behind),
+      String(r.dirty),
+      r.last_commit ?? "-",
+      (r.last_commit_subject ?? "").split("\n")[0]?.slice(0, 60) ?? ""
+    ]);
+    const widths = headers.map(
+      (h, i) => Math.max(h.length, ...data.map((row) => (row[i] ?? "").length))
+    );
+    const fmt = (row) => row.map((c, i) => c.padEnd(widths[i] ?? 0)).join("  ");
+    emit(fmt(headers));
+    for (const row of data) emit(fmt(row));
+  });
+  repoOption(
+    program.command("commit").description("Commit pending changes across selected repos.").requiredOption("-m, --message <msg>", "Commit message.").option("--allow-empty", "Allow empty commits.")
+  ).action(
+    async (opts, cmd) => {
+      const root = inheritRootOptions(cmd);
+      if (!opts.message || opts.message.trim().length === 0) {
+        throw new UserError(`Commit message must not be empty.`);
+      }
+      const { repos } = await loadProjectRepos();
+      const selected = await reposPresent(selectRepos(repos, opts.repo));
+      const jobs = resolveJobs(root.jobs);
+      const results = [];
+      await pMap2(
+        selected,
+        async (r) => {
+          try {
+            const res = await gitCommit(r.dir, opts.message, { allowEmpty: Boolean(opts.allowEmpty) });
+            results.push({ repo: r.name, committed: res.committed });
+          } catch (err) {
+            results.push({ repo: r.name, committed: false, error: err instanceof Error ? err.message : String(err) });
+          }
+        },
+        { concurrency: jobs }
+      );
+      if (root.json) {
+        emitJson({ results });
+        return;
+      }
+      for (const r of results) {
+        const verb = r.committed ? "committed" : r.error ? "failed" : "skipped";
+        emit(`${verb.padEnd(10)} ${r.repo}${r.error ? "  \u2014 " + r.error : ""}`);
+      }
+      if (results.some((r) => r.error)) throw new RuntimeFailure("Some commits failed.");
+    }
+  );
+  repoOption(
+    program.command("push").description("git push the current branch across selected repos.")
+  ).action(async (opts, cmd) => {
+    const root = inheritRootOptions(cmd);
+    const { repos } = await loadProjectRepos();
+    const selected = await reposPresent(selectRepos(repos, opts.repo));
+    const jobs = resolveJobs(root.jobs);
+    const results = [];
+    await pMap2(
+      selected,
+      async (r) => {
+        try {
+          await gitPush(r.dir);
+          results.push({ repo: r.name, ok: true });
+        } catch (err) {
+          results.push({ repo: r.name, ok: false, error: err instanceof Error ? err.message : String(err) });
+        }
+      },
+      { concurrency: jobs }
+    );
+    if (root.json) {
+      emitJson({ results });
+      return;
+    }
+    for (const r of results) emit(`${r.ok ? "ok  " : "fail"} ${r.repo}${r.error ? "  \u2014 " + r.error : ""}`);
+    if (results.some((r) => !r.ok)) throw new RuntimeFailure("Some pushes failed.");
+  });
+  void path11;
+}
+
+// src/cli/commands/prepare.ts
+import pMap4 from "p-map";
+
+// src/manifest/discovery.ts
+import fs8 from "fs/promises";
+import path12 from "path";
+import pMap3 from "p-map";
+var MAX_DEPTH = 4;
+var SKIP_DIRS = /* @__PURE__ */ new Set([
+  ".git",
+  ".qavor",
+  "node_modules",
+  ".venv",
+  "venv",
+  "__pycache__",
+  "dist",
+  "build",
+  "target",
+  ".next",
+  ".svelte-kit",
+  ".cache"
+]);
+async function discoverManifestFiles(repoRoot) {
+  const abs = path12.resolve(repoRoot);
+  const found = /* @__PURE__ */ new Set();
+  if (!await isDirectory(abs)) return [];
+  const rootFile = path12.join(abs, "qavor.yaml");
+  try {
+    await fs8.access(rootFile);
+    found.add(rootFile);
+  } catch {
+  }
+  const qavorDir = path12.join(abs, "qavor");
+  if (await isDirectory(qavorDir)) {
+    for await (const f of walk(qavorDir, qavorDir, 0)) found.add(f);
+  }
+  for await (const f of walk(abs, abs, 0)) {
+    found.add(f);
+  }
+  return [...found].sort();
+}
+async function* walk(rootBase, current, depth) {
+  if (depth > MAX_DEPTH) return;
+  let entries;
+  try {
+    entries = await fs8.readdir(current, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const full = path12.join(current, entry.name);
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      if (depth === 0 && entry.name === "qavor") continue;
+      yield* walk(rootBase, full, depth + 1);
+    } else if (entry.isFile() && entry.name === "qavor.yaml") {
+      if (depth === 0 && current === rootBase) continue;
+      yield full;
+    }
+  }
+}
+async function buildWorkspaceRegistry(opts) {
+  const issues = [];
+  const all = [];
+  const reposList = [];
+  for (const [name, dir] of opts.repos) reposList.push({ name, dir });
+  await pMap3(
+    reposList,
+    async ({ name: repoName, dir }) => {
+      const files = await discoverManifestFiles(dir);
+      for (const file of files) {
+        let docs;
+        try {
+          docs = await loadManifestFile(file);
+        } catch (err) {
+          issues.push({
+            file,
+            line: 1,
+            column: 1,
+            kind: "unknown",
+            path: "",
+            message: err instanceof Error ? err.message : String(err)
+          });
+          continue;
+        }
+        for (const doc of docs) {
+          if (!isKnownKind(doc.kind)) {
+            const pos = doc.position("/kind");
+            issues.push({
+              file: pos.file,
+              line: pos.line,
+              column: pos.column,
+              kind: String(doc.kind ?? "unknown"),
+              path: "/kind",
+              message: `Unknown or missing kind in this document`
+            });
+            continue;
+          }
+          const result = validateDocument(doc);
+          if (!result.ok) {
+            issues.push(...result.issues);
+            continue;
+          }
+          const data = doc.data;
+          all.push({
+            kind: doc.kind,
+            name: typeof data.name === "string" ? data.name : "",
+            file: doc.file,
+            docIndex: doc.docIndex,
+            dir: path12.dirname(doc.file),
+            repo: repoName,
+            data: doc.data,
+            position: doc.position
+          });
+        }
+      }
+    },
+    { concurrency: opts.concurrency ?? 8 }
+  );
+  const byName = /* @__PURE__ */ new Map();
+  for (const entry of all) {
+    if (!entry.name) continue;
+    if (entry.kind === "workspaces" || entry.kind === "project") continue;
+    const key = entry.name;
+    const existing = byName.get(key);
+    if (existing && existing.kind === entry.kind) {
+      const pos = entry.position("/name");
+      issues.push({
+        file: pos.file,
+        line: pos.line,
+        column: pos.column,
+        kind: entry.kind,
+        path: "/name",
+        message: `Duplicate ${entry.kind} name '${entry.name}'. Already declared at ${existing.file}.`
+      });
+      continue;
+    }
+    if (!existing) byName.set(key, entry);
+  }
+  return { byName, entries: all, issues };
+}
+
+// src/prepare/prepare.ts
+import { createHash as createHash3 } from "crypto";
+import { createReadStream as createReadStream2 } from "fs";
+import fs10 from "fs/promises";
+import path14 from "path";
+import { execa as execa3 } from "execa";
+
+// src/env/composer.ts
+import path13 from "path";
+
+// src/env/dotenv.ts
+import fs9 from "fs/promises";
+async function loadDotenvFile(file) {
+  if (!await pathExists(file)) return [];
+  const raw = await fs9.readFile(file, "utf8");
+  const lines = raw.split(/\r?\n/);
+  const out = [];
+  for (let i = 0; i < lines.length; i++) {
+    const raw2 = lines[i] ?? "";
+    const line = raw2.trim();
+    if (!line || line.startsWith("#")) continue;
+    const stripped = line.startsWith("export ") ? line.slice("export ".length).trimStart() : line;
+    const eq = stripped.indexOf("=");
+    if (eq <= 0) continue;
+    const key = stripped.slice(0, eq).trim();
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue;
+    let value = stripped.slice(eq + 1);
+    if (!value.startsWith('"') && !value.startsWith("'")) {
+      const hash = value.indexOf(" #");
+      if (hash >= 0) value = value.slice(0, hash);
+      value = value.trim();
+    } else {
+      const quote = value[0];
+      const closing = value.lastIndexOf(quote);
+      if (closing > 0) value = value.slice(1, closing);
+    }
+    out.push({ key, value, file, line: i + 1 });
+  }
+  return out;
+}
+
+// src/env/composer.ts
+async function composeServiceEnv(input) {
+  const issues = [];
+  const layers = [];
+  const manifestDir = path13.dirname(input.serviceDoc.file);
+  const env = input.service.env;
+  const positionFor = input.serviceDoc.position;
+  if (env?.common) {
+    pushEnvMap(layers, env.common, "service.env.common", input.serviceDoc.file, positionFor, "/env/common");
+  }
+  if (input.mode === "native" && env?.native) {
+    pushEnvMap(layers, env.native, "service.env.native", input.serviceDoc.file, positionFor, "/env/native");
+  } else if (input.mode === "docker" && env?.docker) {
+    pushEnvMap(layers, env.docker, "service.env.docker", input.serviceDoc.file, positionFor, "/env/docker");
+  }
+  const baseDotenv = await loadDotenvFile(path13.join(manifestDir, ".env"));
+  for (const e of baseDotenv) {
+    layers.push({
+      key: e.key,
+      raw: e.value,
+      layer: "service.env",
+      file: e.file,
+      line: e.line,
+      spec: null
+    });
+  }
+  const modeDotenvFile = path13.join(manifestDir, input.mode === "native" ? ".env.native" : ".env.docker");
+  const modeDotenv = await loadDotenvFile(modeDotenvFile);
+  for (const e of modeDotenv) {
+    layers.push({
+      key: e.key,
+      raw: e.value,
+      layer: `service.env.${input.mode}`,
+      file: e.file,
+      line: e.line,
+      spec: null
+    });
+  }
+  const wsEnv = await loadDotenvFile(path13.join(input.workspaceRoot, ".env"));
+  for (const e of wsEnv) {
+    layers.push({
+      key: e.key,
+      raw: e.value,
+      layer: "workspace.env",
+      file: e.file,
+      line: e.line,
+      spec: null
+    });
+  }
+  if (input.cliEnv) {
+    for (const [k, v] of Object.entries(input.cliEnv)) {
+      layers.push({
+        key: k,
+        raw: v,
+        layer: "cli.--env",
+        file: "<cli>",
+        line: 0,
+        spec: null
+      });
+    }
+  }
+  return interpolateLayers(layers, issues);
+}
+function pushEnvMap(layers, map, layerLabel, file, positionFor, basePath) {
+  for (const [key, val] of Object.entries(map)) {
+    const valuePath = `${basePath}/${key}`;
+    const pos = positionFor(valuePath);
+    if (isEnvSpec(val)) {
+      const spec = val;
+      const concrete = typeof spec.value !== "undefined" ? spec.value : typeof spec.default !== "undefined" ? spec.default : void 0;
+      if (typeof concrete === "undefined") {
+        layers.push({
+          key,
+          raw: "",
+          layer: layerLabel,
+          file,
+          line: pos.line,
+          spec
+        });
+        continue;
+      }
+      layers.push({
+        key,
+        raw: String(concrete),
+        layer: layerLabel,
+        file,
+        line: pos.line,
+        spec
+      });
+    } else {
+      layers.push({
+        key,
+        raw: String(val),
+        layer: layerLabel,
+        file,
+        line: pos.line,
+        spec: null
+      });
+    }
+  }
+}
+function isEnvSpec(v) {
+  return Boolean(
+    v && typeof v === "object" && !Array.isArray(v) && ("value" in v || "default" in v || "required" in v || "secret" in v || "type" in v || "pattern" in v || "description" in v)
+  );
+}
+var INTERP_RE = /\$\{([^}]+)\}/g;
+var SECRET_PREFIX = "secret:";
+function interpolateLayers(layers, issues) {
+  const values = /* @__PURE__ */ new Map();
+  for (const entry of layers) {
+    const isRequiredPlaceholder = !entry.raw && entry.spec?.required === true && typeof entry.spec?.value === "undefined" && typeof entry.spec?.default === "undefined";
+    if (isRequiredPlaceholder) {
+      const prior2 = values.get(entry.key);
+      const provenance2 = prior2 ? prior2.provenance.slice() : [];
+      provenance2.push({ file: entry.file, line: entry.line, layer: entry.layer, raw: "" });
+      values.set(entry.key, {
+        value: prior2?.value ?? "",
+        provenance: provenance2,
+        secret: Boolean(entry.spec?.secret) || (prior2?.secret ?? false),
+        required: true
+      });
+      continue;
+    }
+    const { value, missing, secrets } = interpolate(entry.raw, values, process.env);
+    if (secrets.length > 0) {
+      issues.push({
+        file: entry.file,
+        line: entry.line,
+        message: `\${secret:${secrets[0]}} interpolation is reserved for v1. Configure as plain env until then.`
+      });
+      continue;
+    }
+    if (missing.length > 0) {
+      issues.push({
+        file: entry.file,
+        line: entry.line,
+        message: `Unresolved interpolation in ${entry.key}: \${${missing[0]}}`
+      });
+      continue;
+    }
+    const prior = values.get(entry.key);
+    const provenance = prior ? prior.provenance.slice() : [];
+    provenance.push({ file: entry.file, line: entry.line, layer: entry.layer, raw: entry.raw });
+    values.set(entry.key, {
+      value,
+      provenance,
+      secret: Boolean(entry.spec?.secret) || (prior?.secret ?? false),
+      required: Boolean(entry.spec?.required) || (prior?.required ?? false)
+    });
+  }
+  for (const [key, val] of values) {
+    if (val.required && (val.value === "" || typeof val.value === "undefined")) {
+      const last = val.provenance[val.provenance.length - 1];
+      issues.push({
+        file: last?.file ?? "<unknown>",
+        line: last?.line ?? 0,
+        message: `Required env ${key} has no value.`
+      });
+    }
+  }
+  return { values, issues };
+}
+function interpolate(raw, resolved, procEnv) {
+  if (!raw) return { value: raw, missing: [], secrets: [] };
+  const missing = [];
+  const secrets = [];
+  const value = raw.replace(INTERP_RE, (_m, expr) => {
+    const trimmed = expr.trim();
+    if (trimmed.startsWith(SECRET_PREFIX)) {
+      secrets.push(trimmed.slice(SECRET_PREFIX.length));
+      return "";
+    }
+    const fromResolved = resolved.get(trimmed);
+    if (fromResolved) return fromResolved.value;
+    const fromProc = procEnv[trimmed];
+    if (typeof fromProc === "string") return fromProc;
+    missing.push(trimmed);
+    return "";
+  });
+  return { value, missing, secrets };
+}
+function parseCliEnv(items) {
+  const out = {};
+  for (const item of items) {
+    const eq = item.indexOf("=");
+    if (eq <= 0) throw new UserError(`Invalid --env value '${item}'. Expected KEY=VALUE.`);
+    const key = item.slice(0, eq);
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+      throw new UserError(`Invalid env key '${key}' in --env. Use UPPER_SNAKE_CASE.`);
+    }
+    out[key] = item.slice(eq + 1);
+  }
+  return out;
+}
+function toEnvObject(resolved) {
+  const out = {};
+  for (const [k, v] of resolved.values) out[k] = v.value;
+  return out;
+}
+function assertNoIssues(resolved) {
+  if (resolved.issues.length === 0) return;
+  const lines = resolved.issues.map((i) => `${i.file}:${i.line}: ${i.message}`);
+  throw new ManifestError(`Environment composition failed:
+  ${lines.join("\n  ")}`);
+}
+
+// src/util/hooks.ts
+import { execa as execa2 } from "execa";
+function toList(cmds) {
+  if (!cmds) return [];
+  return Array.isArray(cmds) ? [...cmds] : [cmds];
+}
+async function runHooks(opts) {
+  const cmds = toList(opts.hooks?.[opts.event]);
+  if (cmds.length === 0) return;
+  for (const cmd of cmds) {
+    opts.logger.info({ event: opts.event, cmd }, "hook: running");
+    try {
+      await execa2("/bin/sh", ["-c", cmd], {
+        cwd: opts.cwd,
+        env: opts.env ? { ...process.env, ...opts.env } : process.env,
+        stdout: "inherit",
+        stderr: "inherit",
+        ...opts.signal ? { cancelSignal: opts.signal } : {}
+      });
+    } catch (err) {
+      throw new RuntimeFailure(
+        `Hook ${opts.event} failed (${cmd}): ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+}
+
+// src/prepare/prepare.ts
+var DEFAULT_LOCK_PATTERNS = [
+  "package-lock.json",
+  "pnpm-lock.yaml",
+  "yarn.lock",
+  "uv.lock",
+  "poetry.lock",
+  "requirements.txt",
+  "Pipfile.lock",
+  "go.sum",
+  "Cargo.lock"
+];
+async function prepareService(input) {
+  const cmd = input.service.runtime?.native?.prepare?.cmd;
+  if (!cmd) {
+    return {
+      serviceName: input.service.name,
+      status: "no-prepare-cmd",
+      cacheFile: "",
+      hash: null
+    };
+  }
+  const manifestDir = path14.dirname(input.serviceDoc.file);
+  const cacheFile = path14.join(input.paths.cacheDir, "prepare", `${input.service.name}.json`);
+  const hash = await computePrepareHash(manifestDir, cmd);
+  if (!input.force) {
+    const prev = await readPrev(cacheFile);
+    if (prev && prev.hash === hash) {
+      input.logger.info({ service: input.service.name }, "prepare: lockfile hash unchanged; skipping");
+      return { serviceName: input.service.name, status: "skipped", cacheFile, hash };
+    }
+  }
+  const envRes = await composeServiceEnv({
+    mode: "native",
+    serviceDoc: input.serviceDoc,
+    service: input.service,
+    workspaceRoot: input.paths.root,
+    ...input.cliEnv ? { cliEnv: input.cliEnv } : {}
+  });
+  assertNoIssues(envRes);
+  const env = toEnvObject(envRes);
+  await runHooks({
+    hooks: input.service.hooks,
+    event: "pre_prepare",
+    cwd: manifestDir,
+    env,
+    logger: input.logger,
+    ...input.signal ? { signal: input.signal } : {}
+  });
+  await ensureDir(path14.join(input.paths.logsDir, input.service.name));
+  const logFile = path14.join(input.paths.logsDir, input.service.name, "prepare.log");
+  input.logger.info({ service: input.service.name, cmd }, "prepare: starting");
+  const cwd = input.service.runtime?.native?.prepare?.cwd ? path14.resolve(manifestDir, input.service.runtime.native.prepare.cwd) : manifestDir;
+  const fileHandle = await fs10.open(logFile, "a");
+  const shell = input.service.runtime?.native?.prepare?.shell ?? "/bin/sh";
+  try {
+    const opts = {
+      cwd,
+      env: { ...process.env, ...env },
+      stdio: ["ignore", fileHandle.fd, fileHandle.fd],
+      ...input.signal ? { cancelSignal: input.signal } : {},
+      reject: false
+    };
+    const res = await execa3(shell, ["-c", cmd], opts);
+    if (res.exitCode !== 0) {
+      throw new RuntimeFailure(
+        `prepare failed for ${input.service.name} (exit ${res.exitCode}). See ${logFile}.`
+      );
+    }
+  } catch (err) {
+    if (err instanceof RuntimeFailure) throw err;
+    const message = err instanceof Error ? err.message : String(err);
+    throw new RuntimeFailure(
+      `prepare failed for ${input.service.name}: ${message}. See ${logFile}.`
+    );
+  } finally {
+    await fileHandle.close();
+  }
+  await runHooks({
+    hooks: input.service.hooks,
+    event: "post_prepare",
+    cwd: manifestDir,
+    env,
+    logger: input.logger,
+    ...input.signal ? { signal: input.signal } : {}
+  });
+  await writeJsonFile(cacheFile, {
+    service: input.service.name,
+    hash,
+    at: (/* @__PURE__ */ new Date()).toISOString(),
+    cmd
+  });
+  return { serviceName: input.service.name, status: "ok", cacheFile, hash };
+}
+async function readPrev(file) {
+  if (!await pathExists(file)) return null;
+  try {
+    return await readJsonFile(file);
+  } catch {
+    return null;
+  }
+}
+async function computePrepareHash(manifestDir, cmd) {
+  const hash = createHash3("sha256");
+  hash.update("cmd:" + cmd + "\n");
+  for (const candidate of DEFAULT_LOCK_PATTERNS) {
+    const file = path14.join(manifestDir, candidate);
+    const stat = await safeStat(file);
+    if (!stat) {
+      hash.update(`missing:${candidate}
+`);
+      continue;
+    }
+    hash.update(`file:${candidate}
+size:${stat.size}
+mtime:${stat.mtimeMs}
+`);
+    const fileHash = await hashFile(file);
+    hash.update(`sha:${fileHash}
+`);
+  }
+  return hash.digest("hex");
+}
+async function safeStat(file) {
+  try {
+    return await fs10.stat(file);
+  } catch {
+    return null;
+  }
+}
+async function hashFile(file) {
+  const hash = createHash3("sha256");
+  const stream = createReadStream2(file);
+  for await (const chunk of stream) hash.update(chunk);
+  return hash.digest("hex");
+}
+
+// src/cli/commands/prepare.ts
+function registerPrepare(program) {
+  program.command("prepare").description("Run `runtime.native.prepare` for every selected service (lockfile-aware skip).").option("--repo <name...>", "Limit to services in the given repo(s).").option("--service <name...>", "Limit to specific service names.").option("--force", "Re-run prepare even when the lockfile hash matches the cache.").option("--env <kv...>", "Override env values, KEY=VAL.").action(
+    async (opts, cmd) => {
+      const root = inheritRootOptions(cmd);
+      const logger = getLogger();
+      const ws = await resolveWorkspace();
+      const projectDoc = await readProjectManifest(ws.projectManifestFile);
+      const allRepos = resolveRepos({
+        workspaceRoot: ws.paths.root,
+        project: projectDoc.data,
+        projectRepoPath: ws.projectRepoPath
+      });
+      const selectedRepos = selectRepos(allRepos, opts.repo);
+      const repoMap = new Map(selectedRepos.map((r) => [r.name, r.dir]));
+      if (!opts.repo) repoMap.set("__project__", ws.projectRepoPath);
+      const registry = await buildWorkspaceRegistry({
+        workspaceRoot: ws.paths.root,
+        repos: repoMap,
+        concurrency: resolveJobs(root.jobs)
+      });
+      for (const issue of registry.issues) {
+        logger.warn(
+          { file: issue.file, line: issue.line, message: issue.message },
+          "manifest issue"
+        );
+      }
+      let services = registry.entries.filter((e) => e.kind === "service");
+      if (opts.service && opts.service.length > 0) {
+        const set = new Set(opts.service);
+        services = services.filter((s) => set.has(s.name));
+        const missing = [...set].filter((n) => !services.some((s) => s.name === n));
+        if (missing.length > 0) {
+          throw new UserError(`Unknown service(s): ${missing.join(", ")}`);
+        }
+      }
+      const cliEnv = opts.env ? parseCliEnv(opts.env) : void 0;
+      const jobs = resolveJobs(root.jobs);
+      const results = await pMap4(
+        services,
+        async (entry) => {
+          const docs = await loadManifestFile(entry.file);
+          const serviceDoc = docs[entry.docIndex];
+          const service = entry.data;
+          const prepareOpts = {
+            paths: ws.paths,
+            serviceDoc,
+            service,
+            force: Boolean(opts.force),
+            logger
+          };
+          if (cliEnv) prepareOpts.cliEnv = cliEnv;
+          return prepareService(prepareOpts);
+        },
+        { concurrency: jobs }
+      );
+      if (root.json) {
+        emitJson({ results });
+        return;
+      }
+      for (const r of results) {
+        emit(`${r.status.padEnd(15)} ${r.serviceName}`);
+      }
+    }
+  );
+}
+
+// src/cli/commands/env.ts
+function registerEnv(program) {
+  program.command("env").description("Print the fully-resolved environment for a service, with provenance per key.").argument("<service>", "Service name.").option("--mode <mode>", "native | docker (default: native).", "native").option("--env <kv...>", "Layer KEY=VAL on top of the composed env.").action(async (service, opts, cmd) => {
+    const root = inheritRootOptions(cmd);
+    const mode = opts.mode === "docker" ? "docker" : "native";
+    if (opts.mode !== "native" && opts.mode !== "docker") {
+      throw new UserError(`--mode must be 'native' or 'docker'.`);
+    }
+    const ws = await resolveWorkspace();
+    const projectDoc = await readProjectManifest(ws.projectManifestFile);
+    const repos = resolveRepos({
+      workspaceRoot: ws.paths.root,
+      project: projectDoc.data,
+      projectRepoPath: ws.projectRepoPath
+    });
+    const repoMap = new Map(repos.map((r) => [r.name, r.dir]));
+    repoMap.set("__project__", ws.projectRepoPath);
+    const registry = await buildWorkspaceRegistry({
+      workspaceRoot: ws.paths.root,
+      repos: repoMap,
+      concurrency: resolveJobs(root.jobs)
+    });
+    const entry = registry.entries.find((e) => e.kind === "service" && e.name === service);
+    if (!entry) throw new UserError(`Service '${service}' not found in workspace.`);
+    const docs = await loadManifestFile(entry.file);
+    const serviceDoc = docs[entry.docIndex];
+    const cliEnv = opts.env ? parseCliEnv(opts.env) : void 0;
+    const composeOpts = {
+      mode,
+      serviceDoc,
+      service: entry.data,
+      workspaceRoot: ws.paths.root
+    };
+    if (cliEnv) composeOpts.cliEnv = cliEnv;
+    const resolved = await composeServiceEnv(composeOpts);
+    if (root.json) {
+      emitJson({
+        service,
+        mode,
+        issues: resolved.issues,
+        env: [...resolved.values].map(([k, v]) => ({
+          key: k,
+          value: v.secret ? "<redacted>" : v.value,
+          secret: v.secret,
+          required: v.required,
+          provenance: v.provenance.map((p) => ({
+            file: p.file,
+            line: p.line,
+            layer: p.layer,
+            raw: v.secret ? "<redacted>" : p.raw
+          }))
+        }))
+      });
+      return;
+    }
+    if (resolved.issues.length > 0) {
+      emit("Issues:");
+      for (const i of resolved.issues) emit(`  ${i.file}:${i.line}: ${i.message}`);
+      emit("");
+    }
+    emit(`Resolved environment for ${service} (mode=${mode}):`);
+    for (const [k, v] of resolved.values) {
+      const printed = v.secret ? "<redacted>" : v.value;
+      emit(`  ${k} = ${printed}`);
+      for (const p of v.provenance) {
+        const rawPrinted = v.secret ? "<redacted>" : p.raw;
+        emit(`    via ${p.layer} (${p.file}:${p.line}) = ${rawPrinted}`);
+      }
+    }
+  });
+}
+
+// src/supervisor/native.ts
+import fs12 from "fs/promises";
+import path16 from "path";
+import { execa as execa4 } from "execa";
+
+// src/supervisor/state.ts
+import fs11 from "fs/promises";
+import path15 from "path";
+function stateFile(paths, service) {
+  return path15.join(paths.stateDir, `${service}.json`);
+}
+async function readState(paths, service) {
+  const file = stateFile(paths, service);
+  if (!await pathExists(file)) return null;
+  try {
+    return await readJsonFile(file);
+  } catch {
+    return null;
+  }
+}
+async function writeState(paths, state) {
+  state.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+  await writeJsonFile(stateFile(paths, state.service), state);
+}
+async function clearState(paths, service) {
+  const file = stateFile(paths, service);
+  try {
+    await fs11.unlink(file);
+  } catch (err) {
+    if (err.code !== "ENOENT") throw err;
+  }
+}
+function isPidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    const e = err;
+    if (e.code === "EPERM") return true;
+    return false;
+  }
+}
+async function listSupervisorStates(paths) {
+  const out = [];
+  if (!await pathExists(paths.stateDir)) return out;
+  const entries = await fs11.readdir(paths.stateDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
+    try {
+      const state = await readJsonFile(path15.join(paths.stateDir, entry.name));
+      out.push(state);
+    } catch {
+    }
+  }
+  return out;
+}
+
+// src/supervisor/native.ts
+var LOG_FILE_NAME = "service.log";
+var LOG_MAX_BYTES = 5 * 1024 * 1024;
+var LOG_BACKLOG = 5;
+async function startNativeService(opts) {
+  const cmd = opts.service.runtime?.native?.run?.cmd;
+  if (!cmd) {
+    throw new UserError(
+      `Service '${opts.service.name}' has no runtime.native.run.cmd. Cannot start in native mode.`
+    );
+  }
+  if (opts.service.runtime?.native?.enabled === false) {
+    throw new UserError(
+      `Service '${opts.service.name}' has runtime.native.enabled: false. Cannot start in native mode.`
+    );
+  }
+  const existing = await readState(opts.paths, opts.service.name);
+  if (existing && existing.status === "running" && isPidAlive(existing.pid)) {
+    throw new UserError(`Service '${opts.service.name}' is already running (pid ${existing.pid}).`);
+  }
+  const manifestDir = path16.dirname(opts.serviceDoc.file);
+  const cwd = opts.service.runtime?.native?.run?.cwd ? path16.resolve(manifestDir, opts.service.runtime.native.run.cwd) : manifestDir;
+  const envRes = await composeServiceEnv({
+    mode: "native",
+    serviceDoc: opts.serviceDoc,
+    service: opts.service,
+    workspaceRoot: opts.paths.root,
+    ...opts.cliEnv ? { cliEnv: opts.cliEnv } : {}
+  });
+  assertNoIssues(envRes);
+  const env = toEnvObject(envRes);
+  const serviceLogDir = path16.join(opts.paths.logsDir, opts.service.name);
+  await ensureDir(serviceLogDir);
+  await rotateLog(serviceLogDir);
+  const logFile = path16.join(serviceLogDir, LOG_FILE_NAME);
+  const fh = await fs12.open(logFile, "a");
+  await runHooks({
+    hooks: opts.service.hooks,
+    event: "pre_run",
+    cwd: manifestDir,
+    env,
+    logger: opts.logger
+  });
+  let child;
+  const shell = opts.service.runtime?.native?.run?.shell ?? "/bin/sh";
+  try {
+    const spawnOpts = {
+      cwd,
+      env: { ...process.env, ...env },
+      detached: true,
+      stdio: ["ignore", fh.fd, fh.fd],
+      reject: false
+    };
+    child = execa4(shell, ["-c", cmd], spawnOpts);
+  } catch (err) {
+    await fh.close().catch(() => void 0);
+    throw new RuntimeFailure(
+      `Failed to spawn ${opts.service.name}: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  const pid = child.pid ?? 0;
+  if (!pid) {
+    await fh.close().catch(() => void 0);
+    throw new RuntimeFailure(`Failed to spawn ${opts.service.name}: no pid assigned.`);
+  }
+  child.unref();
+  await fh.close().catch(() => void 0);
+  const state = {
+    service: opts.service.name,
+    pid,
+    pgid: pid,
+    startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    cmd,
+    cwd,
+    logFile,
+    status: "running",
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  await writeState(opts.paths, state);
+  opts.logger.info({ service: opts.service.name, pid, logFile }, "up: started");
+  return { pid, pgid: pid, logFile };
+}
+var DEFAULT_GRACE_MS = 1e4;
+async function stopNativeService(opts) {
+  const state = await readState(opts.paths, opts.service);
+  if (!state) {
+    opts.logger.info({ service: opts.service }, "down: no state file; nothing to do");
+    return { stopped: false };
+  }
+  if (!isPidAlive(state.pid)) {
+    opts.logger.info({ service: opts.service, pid: state.pid }, "down: process already gone; clearing state");
+    await clearState(opts.paths, opts.service);
+    return { stopped: true };
+  }
+  if (opts.manifestDir && opts.hooks) {
+    await runHooks({
+      hooks: opts.hooks,
+      event: "pre_stop",
+      cwd: opts.manifestDir,
+      logger: opts.logger
+    });
+  }
+  const grace = opts.graceMs ?? DEFAULT_GRACE_MS;
+  try {
+    process.kill(-state.pid, "SIGTERM");
+  } catch (err) {
+    const e = err;
+    if (e.code !== "ESRCH") throw err;
+  }
+  const stoppedGracefully = await waitForExit(state.pid, grace);
+  if (!stoppedGracefully) {
+    opts.logger.warn({ service: opts.service, pid: state.pid }, "down: grace exceeded; SIGKILL");
+    try {
+      process.kill(-state.pid, "SIGKILL");
+    } catch (err) {
+      const e = err;
+      if (e.code !== "ESRCH") throw err;
+    }
+    await waitForExit(state.pid, 5e3);
+  }
+  if (opts.manifestDir && opts.hooks) {
+    await runHooks({
+      hooks: opts.hooks,
+      event: "post_stop",
+      cwd: opts.manifestDir,
+      logger: opts.logger
+    });
+  }
+  await clearState(opts.paths, opts.service);
+  return { stopped: true };
+}
+async function waitForExit(pid, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!isPidAlive(pid)) return true;
+    await sleep(100);
+  }
+  return false;
+}
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+async function rotateLog(dir) {
+  const main2 = path16.join(dir, LOG_FILE_NAME);
+  let st = null;
+  try {
+    st = await fs12.stat(main2);
+  } catch {
+    return;
+  }
+  if (st.size < LOG_MAX_BYTES) return;
+  for (let i = LOG_BACKLOG - 1; i >= 1; i--) {
+    const src = path16.join(dir, `${LOG_FILE_NAME}.${i}`);
+    const dst = path16.join(dir, `${LOG_FILE_NAME}.${i + 1}`);
+    try {
+      await fs12.rename(src, dst);
+    } catch {
+    }
+  }
+  try {
+    await fs12.rename(main2, path16.join(dir, `${LOG_FILE_NAME}.1`));
+  } catch {
+  }
+}
+async function listServicesState(paths) {
+  const states = await listSupervisorStates(paths);
+  const out = [];
+  for (const s of states) {
+    const alive = isPidAlive(s.pid);
+    const status = alive ? "running" : s.status === "running" ? "crashed" : "stopped";
+    const started = new Date(s.startedAt);
+    const uptimeSec = alive ? Math.floor((Date.now() - started.getTime()) / 1e3) : null;
+    out.push({
+      service: s.service,
+      status,
+      pid: alive ? s.pid : null,
+      startedAt: s.startedAt,
+      uptimeSec,
+      logFile: s.logFile
+    });
+  }
+  return out;
+}
+
+// src/supervisor/logs.ts
+import fs13 from "fs/promises";
+import { createReadStream as createReadStream3 } from "fs";
+import path17 from "path";
+async function tailFile(opts) {
+  if (!await pathExists(opts.file)) {
+    if (!opts.follow) return;
+    await waitForFile(opts.file, opts.signal);
+  }
+  let offset = await initialOffset(opts.file, opts.initialBytes ?? 16 * 1024);
+  await streamFrom(opts.file, offset, opts.out);
+  if (!opts.follow) return;
+  let stat = await fs13.stat(opts.file);
+  offset = stat.size;
+  const watcher = fs13.watch(opts.file, { persistent: true });
+  const abort = opts.signal ?? new AbortController().signal;
+  const pollTimer = setInterval(async () => {
+    try {
+      const cur = await fs13.stat(opts.file);
+      if (cur.size < offset) {
+        offset = 0;
+      }
+      if (cur.size > offset) {
+        await streamFrom(opts.file, offset, opts.out);
+        offset = cur.size;
+      }
+    } catch {
+    }
+  }, 500);
+  try {
+    for await (const _event of watcher) {
+      if (abort.aborted) break;
+      const cur = await fs13.stat(opts.file).catch(() => null);
+      if (!cur) continue;
+      if (cur.size < offset) {
+        offset = 0;
+      }
+      if (cur.size > offset) {
+        await streamFrom(opts.file, offset, opts.out);
+        offset = cur.size;
+      }
+    }
+  } catch (err) {
+    if (err.code === "ABORT_ERR") return;
+    throw err;
+  } finally {
+    clearInterval(pollTimer);
+  }
+}
+async function initialOffset(file, fromEndBytes) {
+  const st = await fs13.stat(file);
+  return Math.max(0, st.size - fromEndBytes);
+}
+async function streamFrom(file, start, out) {
+  return new Promise((resolve, reject) => {
+    const rs = createReadStream3(file, { start, encoding: "utf8" });
+    rs.on("data", (chunk) => out.write(chunk));
+    rs.on("end", () => resolve());
+    rs.on("error", (err) => reject(err));
+  });
+}
+async function waitForFile(file, signal) {
+  const dir = path17.dirname(file);
+  await fs13.mkdir(dir, { recursive: true });
+  for (; ; ) {
+    if (signal?.aborted) return;
+    if (await pathExists(file)) return;
+    await new Promise((r) => setTimeout(r, 250));
+  }
+}
+
+// src/cli/commands/run.ts
+import path18 from "path";
+async function findService(name, jobs) {
+  const ws = await resolveWorkspace();
+  const projectDoc = await readProjectManifest(ws.projectManifestFile);
+  const repos = resolveRepos({
+    workspaceRoot: ws.paths.root,
+    project: projectDoc.data,
+    projectRepoPath: ws.projectRepoPath
+  });
+  const repoMap = new Map(repos.map((r) => [r.name, r.dir]));
+  repoMap.set("__project__", ws.projectRepoPath);
+  const registry = await buildWorkspaceRegistry({
+    workspaceRoot: ws.paths.root,
+    repos: repoMap,
+    concurrency: jobs
+  });
+  const entry = registry.entries.find((e) => e.kind === "service" && e.name === name);
+  if (!entry) throw new UserError(`Service '${name}' not found in workspace.`);
+  const docs = await loadManifestFile(entry.file);
+  const serviceDoc = docs[entry.docIndex];
+  return {
+    serviceDoc,
+    service: entry.data,
+    paths: ws.paths,
+    manifestDir: path18.dirname(entry.file)
+  };
+}
+function registerRunCommands(program) {
+  program.command("up").description("Start a single service in native mode.").argument("<service>").option("--mode <mode>", "native | docker (default native; docker is v1).", "native").option("--env <kv...>", "KEY=VAL overrides.").action(async (name, opts, cmd) => {
+    const root = inheritRootOptions(cmd);
+    const logger = getLogger();
+    if (opts.mode === "docker") {
+      throw new UserError(`--mode docker is deferred to v1.`);
+    }
+    const cliEnv = opts.env ? parseCliEnv(opts.env) : void 0;
+    const jobs = resolveJobs(root.jobs);
+    const ctx = await findService(name, jobs);
+    const startOpts = {
+      paths: ctx.paths,
+      serviceDoc: ctx.serviceDoc,
+      service: ctx.service,
+      logger
+    };
+    if (cliEnv) startOpts.cliEnv = cliEnv;
+    const result = await startNativeService(startOpts);
+    if (root.json) {
+      emitJson({ service: name, pid: result.pid, logFile: result.logFile });
+    } else {
+      emit(`Started ${name} pid=${result.pid}`);
+      emit(`  log file: ${result.logFile}`);
+      emit(`  tail with: qavor logs ${name} -f`);
+    }
+  });
+  program.command("down").description("Stop a single running service gracefully.").argument("<service>").option("--grace <ms>", "Grace period for SIGTERM before SIGKILL (default 10000).", "10000").action(async (name, opts, cmd) => {
+    const root = inheritRootOptions(cmd);
+    const logger = getLogger();
+    const jobs = resolveJobs(root.jobs);
+    const ctx = await findService(name, jobs);
+    const graceMs = Number.parseInt(opts.grace, 10);
+    const res = await stopNativeService({
+      paths: ctx.paths,
+      service: name,
+      manifestDir: ctx.manifestDir,
+      ...ctx.service.hooks ? { hooks: ctx.service.hooks } : {},
+      graceMs: Number.isFinite(graceMs) ? graceMs : 1e4,
+      logger
+    });
+    if (root.json) {
+      emitJson({ service: name, stopped: res.stopped });
+    } else {
+      emit(`${res.stopped ? "Stopped" : "No-op"} ${name}`);
+    }
+  });
+  program.command("logs").description("Print or tail a service log file.").argument("<service>").option("-f, --follow", "Follow the log file as new lines append.").option("--bytes <n>", "Initial bytes from the tail to print (default 16384).", "16384").action(async (name, opts, cmd) => {
+    const root = inheritRootOptions(cmd);
+    const jobs = resolveJobs(root.jobs);
+    const ctx = await findService(name, jobs);
+    const logFile = path18.join(ctx.paths.logsDir, name, "service.log");
+    const ac = new AbortController();
+    process.on("SIGINT", () => ac.abort());
+    process.on("SIGTERM", () => ac.abort());
+    await tailFile({
+      file: logFile,
+      out: process.stdout,
+      follow: Boolean(opts.follow),
+      signal: ac.signal,
+      initialBytes: Number.parseInt(opts.bytes, 10) || 16 * 1024
+    });
+    void root;
+  });
+  program.command("ps").description("List services tracked by the supervisor.").action(async (_opts, cmd) => {
+    const root = inheritRootOptions(cmd);
+    const ws = await resolveWorkspace();
+    const list = await listServicesState(ws.paths);
+    if (root.json) {
+      emitJson({ services: list });
+      return;
+    }
+    if (list.length === 0) {
+      emit("(no services tracked)");
+      return;
+    }
+    const headers = ["SERVICE", "STATUS", "PID", "UPTIME", "LOG"];
+    const data = list.map((s) => [
+      s.service,
+      s.status,
+      s.pid !== null ? String(s.pid) : "-",
+      s.uptimeSec !== null ? `${s.uptimeSec}s` : "-",
+      s.logFile ?? "-"
+    ]);
+    const widths = headers.map((h, i) => Math.max(h.length, ...data.map((row) => (row[i] ?? "").length)));
+    const fmt = (row) => row.map((c, i) => c.padEnd(widths[i] ?? 0)).join("  ");
+    emit(fmt(headers));
+    for (const row of data) emit(fmt(row));
+  });
+}
+
+// src/cli/commands/doctor.ts
+import path19 from "path";
+import fs14 from "fs/promises";
+import { execa as execa5 } from "execa";
+async function runShell(cmd, cwd) {
+  try {
+    const res = await execa5("/bin/sh", ["-c", cmd], { cwd, reject: false });
+    return { ok: res.exitCode === 0, exitCode: res.exitCode ?? -1 };
+  } catch {
+    return { ok: false, exitCode: -1 };
+  }
+}
+function registerDoctor(program) {
+  program.command("doctor").description("Verify toolchain prerequisites, workspace paths, and per-service check_installed steps.").action(async (_opts, cmd) => {
+    const root = inheritRootOptions(cmd);
+    const logger = getLogger();
+    const checks = [];
+    try {
+      const res = await execa5("git", ["--version"]);
+      const version = res.stdout.trim().replace(/^git version /, "");
+      const [maj, min] = version.split(".").map((s) => Number.parseInt(s, 10));
+      if (Number.isFinite(maj) && Number.isFinite(min) && ((maj ?? 0) > 2 || (maj ?? 0) === 2 && (min ?? 0) >= 30)) {
+        checks.push({ name: "git \u2265 2.30", status: "ok", message: version });
+      } else {
+        checks.push({ name: "git \u2265 2.30", status: "warn", message: `found ${version}` });
+      }
+    } catch {
+      checks.push({ name: "git \u2265 2.30", status: "fail", message: "git not found", hint: "Install git." });
+    }
+    try {
+      await execa5("docker", ["--version"]);
+      checks.push({ name: "docker (optional v0)", status: "ok" });
+    } catch {
+      checks.push({ name: "docker (optional v0)", status: "warn", message: "docker not detected" });
+    }
+    try {
+      const ws = await resolveWorkspace();
+      await ensureDir(ws.paths.stateRoot);
+      const probe = path19.join(ws.paths.stateRoot, ".doctor-write-check");
+      await fs14.writeFile(probe, "");
+      await fs14.unlink(probe);
+      checks.push({ name: "workspace .qavor/ writable", status: "ok", message: ws.paths.stateRoot });
+    } catch (err) {
+      checks.push({
+        name: "workspace .qavor/ writable",
+        status: "fail",
+        message: err instanceof Error ? err.message : String(err)
+      });
+    }
+    const cache = globalCacheDir();
+    try {
+      await ensureDir(cache);
+      const probe = path19.join(cache, ".doctor-write-check");
+      await fs14.writeFile(probe, "");
+      await fs14.unlink(probe);
+      checks.push({ name: "global cache writable", status: "ok", message: cache });
+    } catch (err) {
+      checks.push({
+        name: "global cache writable",
+        status: "fail",
+        message: err instanceof Error ? err.message : String(err)
+      });
+    }
+    try {
+      const ws = await resolveWorkspace();
+      const project = await readProjectManifest(ws.projectManifestFile);
+      const repos = resolveRepos({
+        workspaceRoot: ws.paths.root,
+        project: project.data,
+        projectRepoPath: ws.projectRepoPath
+      });
+      const repoMap = new Map(repos.map((r) => [r.name, r.dir]));
+      repoMap.set("__project__", ws.projectRepoPath);
+      const registry = await buildWorkspaceRegistry({
+        workspaceRoot: ws.paths.root,
+        repos: repoMap,
+        concurrency: resolveJobs(root.jobs)
+      });
+      for (const entry of registry.entries) {
+        if (entry.kind !== "service") continue;
+        const svc = entry.data;
+        const checkCmd = svc.runtime?.native?.check_installed?.cmd;
+        if (!checkCmd) {
+          checks.push({
+            name: `service ${entry.name}: check_installed`,
+            status: "warn",
+            message: "no runtime.native.check_installed.cmd"
+          });
+          continue;
+        }
+        const docs = await loadManifestFile(entry.file);
+        const serviceDoc = docs[entry.docIndex];
+        const cwd = svc.runtime?.native?.check_installed?.cwd ? path19.resolve(path19.dirname(serviceDoc.file), svc.runtime.native.check_installed.cwd) : path19.dirname(serviceDoc.file);
+        const res = await runShell(checkCmd, cwd);
+        if (res.ok) {
+          checks.push({ name: `service ${entry.name}: check_installed`, status: "ok" });
+        } else {
+          const installHint = svc.runtime?.native?.install?.cmd;
+          const failCheck = {
+            name: `service ${entry.name}: check_installed`,
+            status: "fail",
+            message: `exit ${res.exitCode}`
+          };
+          if (installHint) failCheck.hint = `Hint: \`${installHint}\``;
+          checks.push(failCheck);
+        }
+      }
+    } catch (err) {
+      logger.debug({ err: err instanceof Error ? err.message : String(err) }, "doctor: workspace probe failed");
+    }
+    if (root.json) {
+      emitJson({ checks, ok: checks.every((c) => c.status !== "fail") });
+    } else {
+      for (const c of checks) {
+        const sym = c.status === "ok" ? "\u2713" : c.status === "warn" ? "!" : "\u2717";
+        let line = `${sym} ${c.status.toUpperCase().padEnd(5)} ${c.name}`;
+        if (c.message) line += ` \u2014 ${c.message}`;
+        emit(line);
+        if (c.hint) emit(`     ${c.hint}`);
+      }
+    }
+    if (checks.some((c) => c.status === "fail")) {
+      throw new RuntimeFailure("doctor: one or more checks failed.");
+    }
+  });
+}
+
+// src/index.ts
+var PKG_VERSION = "0.1.0";
+function buildProgram() {
+  const program = new Command();
+  program.name("qavor").description("A CLI for managing a constellation of related repositories as one cohesive developer workspace.").version(PKG_VERSION, "-V, --version").option("--json", "Emit machine-readable JSON output. One object per line on stdout.").option("-v, --verbose", "Enable debug-level logging on stderr.").option("-c, --config <path>", "Override the path to the workspace pointer file.").option("-j, --jobs <n>", "Maximum concurrency for fan-out operations.", (raw) => {
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n < 1) {
+      throw new Error(`--jobs must be a positive integer (got '${raw}').`);
+    }
+    return raw;
+  }).hook("preAction", (thisCommand) => {
+    const opts = thisCommand.opts();
+    configureLogger({ json: Boolean(opts.json), verbose: Boolean(opts.verbose) });
+  });
+  registerInit(program);
+  registerWorkspace(program);
+  registerValidate(program);
+  registerGitCommands(program);
+  registerPrepare(program);
+  registerEnv(program);
+  registerRunCommands(program);
+  registerDoctor(program);
+  return program;
+}
+async function main(argv) {
+  const program = buildProgram();
+  try {
+    await program.parseAsync(argv, { from: "node" });
+    return ExitCode.Ok;
+  } catch (err) {
+    return handleError(err);
+  }
+}
+function handleError(err) {
+  const e = err;
+  if (e && (e.code === "commander.helpDisplayed" || e.code === "commander.help")) return ExitCode.Ok;
+  if (e && e.code === "commander.version") return ExitCode.Ok;
+  if (e && typeof e.code === "string" && e.code.startsWith("commander.")) {
+    process2.stderr.write(`${e.message ?? "command error"}
+`);
+    return ExitCode.UserError;
+  }
+  if (err instanceof QavorError) {
+    process2.stderr.write(`${err.message}
+`);
+    return err.exitCode;
+  }
+  const message = err instanceof Error ? err.stack ?? err.message : String(err);
+  try {
+    const logger = getLogger();
+    logger.error({ err: message }, "unhandled error");
+  } catch {
+    process2.stderr.write(`${message}
+`);
+  }
+  return ExitCode.RuntimeError;
+}
+var code = await main(process2.argv);
+process2.exit(code);
+//# sourceMappingURL=index.js.map