@amsterdamdatalabs/adl-agent-control-darwin-arm64 0.1.4

package/packages/agent-skills/src/profile.ts

@@ -0,0 +1,128 @@
+/**
+ * The deploy profile: which on-disk folder each agent surface reads its
+ * skills from (packages/agent-skills/deploy-profile.json, shaped by
+ * ./deploy-profile.schema.json — both at the package root, never under
+ * src/, since they are data, not code).
+ *
+ * `DEFAULT_PROFILE_PATH`/`DEFAULT_PROFILE_SCHEMA_PATH` resolve relative to
+ * THIS module's own on-disk location, which only means anything for
+ * uncompiled use (`bun run`/`bun test`, a real checkout on disk) — exactly
+ * the caveat apps/cli/src/commands/repo-controls.ts documents for its own
+ * package-root resolution. A caller embedded in a `bun build --compile`
+ * binary (apps/cli's `adl`) must resolve real paths itself and pass them in
+ * explicitly; every exported function here takes its paths as parameters
+ * rather than reaching for the defaults itself.
+ */
+import Ajv, { type ErrorObject, type ValidateFunction } from "ajv";
+import addFormats from "ajv-formats";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+export interface SkillSurface {
+  readonly name: string;
+  readonly folder: string;
+}
+
+export interface DeployProfile {
+  readonly surfaces: readonly SkillSurface[];
+  /**
+   * Repo-relative skill folders no surface reads any more (e.g. old
+   * per-surface copies retired once that surface was confirmed to read a
+   * shared folder instead). deploy.ts removes a skill folder here only when
+   * its name is a skill under assets/; doctor.ts fails while one is still
+   * present. Optional — absent or `[]` means nothing is retired.
+   */
+  readonly retired?: readonly string[];
+  /**
+   * Repo-relative path to the OLD repo-controls engine's per-repo lock
+   * (lockVersion 2), used for a one-time takeover of skill folders it
+   * wrote before this package's own manifest existed — see legacy-lock.ts.
+   * Optional — absent means no legacy lock is considered (a repo the old
+   * engine never set up, or a deploy profile with nothing to take over).
+   */
+  readonly legacyLock?: string;
+}
+
+/** `profile.retired`, defaulted to `[]` — the one place callers should read it from. */
+export function retiredFolders(profile: DeployProfile): readonly string[] {
+  return profile.retired ?? [];
+}
+
+export const DEFAULT_PROFILE_PATH = fileURLToPath(new URL("../deploy-profile.json", import.meta.url));
+export const DEFAULT_PROFILE_SCHEMA_PATH = fileURLToPath(new URL("../deploy-profile.schema.json", import.meta.url));
+
+export interface ProfileIssue {
+  readonly path: string;
+  readonly message: string;
+}
+
+function compileValidator(schemaPath: string): ValidateFunction {
+  const schema = JSON.parse(readFileSync(schemaPath, "utf8"));
+  const ajv = new Ajv({ allErrors: true, strict: true });
+  addFormats(ajv);
+  return ajv.compile(schema);
+}
+
+function formatAjvError(error: ErrorObject): ProfileIssue {
+  const path = error.instancePath.length > 0 ? error.instancePath : "/";
+  return { path, message: `${path} ${error.message ?? "is invalid"}`.trim() };
+}
+
+/**
+ * Validates a parsed deploy-profile document: JSON Schema shape, plus a
+ * semantic check the schema itself cannot express — every surface `name`
+ * and every surface `folder` must be unique. Pure: never throws, never
+ * touches disk beyond reading `schemaPath` once.
+ */
+export function validateProfileDocument(
+  doc: unknown,
+  schemaPath: string = DEFAULT_PROFILE_SCHEMA_PATH,
+): readonly ProfileIssue[] {
+  const validate = compileValidator(schemaPath);
+  if (!validate(doc)) {
+    return (validate.errors ?? []).map(formatAjvError);
+  }
+
+  const { surfaces, retired } = doc as DeployProfile;
+  const issues: ProfileIssue[] = [];
+  const names = new Set<string>();
+  const folders = new Set<string>();
+  for (const surface of surfaces) {
+    if (names.has(surface.name)) issues.push({ path: "/surfaces", message: `duplicate surface name: ${surface.name}` });
+    names.add(surface.name);
+    if (folders.has(surface.folder)) {
+      issues.push({ path: "/surfaces", message: `duplicate surface folder: ${surface.folder}` });
+    }
+    folders.add(surface.folder);
+  }
+
+  const retiredFolderSet = new Set<string>();
+  for (const folder of retired ?? []) {
+    if (retiredFolderSet.has(folder)) issues.push({ path: "/retired", message: `duplicate retired folder: ${folder}` });
+    retiredFolderSet.add(folder);
+    if (folders.has(folder)) {
+      issues.push({ path: "/retired", message: `retired folder is also an active surface folder: ${folder}` });
+    }
+  }
+  return issues;
+}
+
+/** Reads and validates a deploy profile from disk. Throws (fails loud) when the JSON is malformed or the document is invalid — deploy.ts has no way to proceed without a valid profile. */
+export function loadProfile(
+  path: string = DEFAULT_PROFILE_PATH,
+  schemaPath: string = DEFAULT_PROFILE_SCHEMA_PATH,
+): DeployProfile {
+  let doc: unknown;
+  try {
+    doc = JSON.parse(readFileSync(path, "utf8"));
+  } catch (cause) {
+    throw new Error(`deploy profile is not valid JSON: ${path} (${(cause as Error).message})`);
+  }
+  const issues = validateProfileDocument(doc, schemaPath);
+  if (issues.length > 0) {
+    throw new Error(
+      `deploy profile is invalid: ${path}\n${issues.map((issue) => `  - ${issue.path}: ${issue.message}`).join("\n")}`,
+    );
+  }
+  return doc as DeployProfile;
+}

package/packages/agent-skills/src/skill-config.ts

@@ -0,0 +1,75 @@
+/**
+ * Resolves which skills a deploy should write, per the target repo's own
+ * `adl-config.toml`. Absent file, absent `[assets]` table, or absent
+ * `assets.skills` key all mean "deploy everything under assets/" — the
+ * default is always the full set.
+ *
+ * The key is `[assets] skills = [...]`, not a new `[skills]` table:
+ * apps/cli/src/adl-config.ts already declares this exact field
+ * (`AdlConfig.assets.skills`, part of `ADL_CONFIG_SCHEMA`) and that
+ * schema's top level is `additionalProperties: false` against
+ * `{version, repo, assets, controls}` — a competing `[skills]` table would
+ * be an unknown key and rejected by `adl config check`. Reusing the
+ * existing field avoids inventing a second, conflicting mechanism.
+ */
+import TOML from "@iarna/toml";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const ADL_CONFIG_FILE = "adl-config.toml";
+
+export type SkillSubsetResult =
+  | { readonly ok: true; readonly skills: readonly string[] | null } // null = no subset declared
+  | { readonly ok: false; readonly error: string };
+
+export function readSkillSubset(targetRepo: string): SkillSubsetResult {
+  const path = join(targetRepo, ADL_CONFIG_FILE);
+  if (!existsSync(path)) return { ok: true, skills: null };
+
+  let doc: unknown;
+  try {
+    doc = TOML.parse(readFileSync(path, "utf8"));
+  } catch (cause) {
+    return { ok: false, error: `${ADL_CONFIG_FILE} is not valid TOML: ${(cause as Error).message}` };
+  }
+  if (typeof doc !== "object" || doc === null) return { ok: true, skills: null };
+
+  const assets = (doc as Record<string, unknown>).assets;
+  if (assets === undefined) return { ok: true, skills: null };
+  if (typeof assets !== "object" || assets === null || Array.isArray(assets)) {
+    return { ok: false, error: `${ADL_CONFIG_FILE}: [assets] must be a table` };
+  }
+
+  const skills = (assets as Record<string, unknown>).skills;
+  if (skills === undefined) return { ok: true, skills: null };
+  if (!Array.isArray(skills) || !skills.every((entry) => typeof entry === "string")) {
+    return { ok: false, error: `${ADL_CONFIG_FILE}: assets.skills must be an array of strings` };
+  }
+  return { ok: true, skills };
+}
+
+export type SkillSelectionResult =
+  | { readonly ok: true; readonly skills: readonly string[] }
+  | { readonly ok: false; readonly error: string };
+
+/**
+ * Resolves `readSkillSubset` against the skills actually available under
+ * assets/. An unknown skill name in the subset is a hard error — never a
+ * silent skip — so a typo in `adl-config.toml` cannot quietly deploy less
+ * than the repo owner asked for.
+ */
+export function resolveSkillSelection(targetRepo: string, availableSkills: readonly string[]): SkillSelectionResult {
+  const subset = readSkillSubset(targetRepo);
+  if (!subset.ok) return { ok: false, error: subset.error };
+  if (subset.skills === null) return { ok: true, skills: availableSkills };
+
+  const available = new Set(availableSkills);
+  const unknown = subset.skills.filter((name) => !available.has(name));
+  if (unknown.length > 0) {
+    return {
+      ok: false,
+      error: `${ADL_CONFIG_FILE}: assets.skills names skill(s) not present under agent-skills/assets: ${unknown.join(", ")}`,
+    };
+  }
+  return { ok: true, skills: [...new Set(subset.skills)] };
+}

package/packages/agent-skills/src/skill-meta.ts

@@ -0,0 +1,78 @@
+/**
+ * Skill well-formedness: a skill folder is valid when it has a `SKILL.md`
+ * whose YAML front matter declares a non-empty `name` (matching the folder
+ * name) and a non-empty `description`.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import YAML from "yaml";
+
+export interface SkillFrontMatter {
+  readonly name: string;
+  readonly description: string;
+}
+
+export interface SkillMetaIssue {
+  readonly skill: string;
+  readonly path: string;
+  readonly message: string;
+}
+
+/** Directory names directly under `assetsDir`, sorted — the available skill names. */
+export function listSourceSkillNames(assetsDir: string): readonly string[] {
+  return readdirSync(assetsDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort();
+}
+
+function splitFrontMatter(text: string): string | null {
+  const lines = text.split("\n");
+  if (lines[0]?.trim() !== "---") return null;
+  const end = lines.findIndex((line, index) => index > 0 && line.trim() === "---");
+  if (end === -1) return null;
+  return lines.slice(1, end).join("\n");
+}
+
+export function parseSkillFrontMatter(skillMdText: string): SkillFrontMatter | { readonly error: string } {
+  const raw = splitFrontMatter(skillMdText);
+  if (raw === null) return { error: "SKILL.md has no --- front matter block" };
+
+  let parsed: unknown;
+  try {
+    parsed = YAML.parse(raw);
+  } catch (cause) {
+    return { error: `SKILL.md front matter is not valid YAML: ${(cause as Error).message}` };
+  }
+  if (typeof parsed !== "object" || parsed === null) return { error: "SKILL.md front matter must be a YAML mapping" };
+
+  const { name, description } = parsed as Record<string, unknown>;
+  if (typeof name !== "string" || name.length === 0) {
+    return { error: 'SKILL.md front matter is missing a non-empty "name"' };
+  }
+  if (typeof description !== "string" || description.length === 0) {
+    return { error: 'SKILL.md front matter is missing a non-empty "description"' };
+  }
+  return { name, description };
+}
+
+/** Validates one skill folder (source under assets/, or a deployed copy): SKILL.md exists, front matter parses, and its `name` matches the folder name. `[]` when valid. */
+export function validateSkillFolder(skillDir: string, skillName: string): readonly SkillMetaIssue[] {
+  const skillMdPath = join(skillDir, "SKILL.md");
+  if (!existsSync(skillMdPath) || !statSync(skillMdPath).isFile()) {
+    return [{ skill: skillName, path: skillMdPath, message: "SKILL.md is missing" }];
+  }
+
+  const result = parseSkillFrontMatter(readFileSync(skillMdPath, "utf8"));
+  if ("error" in result) return [{ skill: skillName, path: skillMdPath, message: result.error }];
+  if (result.name !== skillName) {
+    return [
+      {
+        skill: skillName,
+        path: skillMdPath,
+        message: `front matter name "${result.name}" does not match folder name "${skillName}"`,
+      },
+    ];
+  }
+  return [];
+}

package/packages/agent-skills/tsconfig.build.json

@@ -0,0 +1,13 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "allowImportingTsExtensions": false,
+    "noEmit": false,
+    "rootDir": "src",
+    "outDir": "dist",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*.ts"]
+}

package/packages/agent-skills/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleResolution": "bundler",
+    "moduleDetection": "force",
+    "types": ["bun"],
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitOverride": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "useUnknownInCatchVariables": true
+  },
+  "include": ["src/**/*.ts", "tests/**/*.ts"]
+}

package/packages/azdo/README.md

@@ -0,0 +1,111 @@
+# azdo — Azure DevOps MCP server and CLI core
+
+Azure DevOps MCP server and direct CLI (PR, build, and work-item tools for `amsterdamdatalabs/Enact`).
+
+**P4 (`docs/architecture/cli-design.md` §7 row P4, §12 Items row 15 — done):**
+the standalone `azure-devops-mcp` binary is folded into the one `adl` binary.
+`apps/cli/src/commands/mcp.ts` statically imports `runMcpServer()`/`runCli()`
+from this package and exposes them as:
+
+- `adl mcp serve` — the MCP server over stdio. Same server, same 7 public
+  tools, same env contract `azure-devops-mcp` (no `cli` arg) had.
+- `adl mcp cli <args…>` — the direct CLI mode `azure-devops-mcp cli …` had,
+  byte-for-byte the same args and output.
+
+`packages/fleet/manifest.json` no longer has an `azure-devops-mcp` entry —
+this package no longer compiles or installs a standalone `azure-devops-mcp`
+binary at all (W5); see "Compiled binary behavior" below for what "folded
+into `adl`" means for how this package's tool dispatch is bundled.
+
+Consuming repositories point their MCP host config at the `adl` binary:
+
+```json
+{ "azure-devops": { "command": "adl", "args": ["mcp", "serve"] } }
+```
+
+## Startup and identity contract
+
+Without arguments, `adl mcp serve` starts the MCP server and **answers
+`initialize`/`tools/list` with no agent identity configured.** The identity
+is resolved lazily on the first tool call by the one identity resolver
+every surface and every Azure DevOps access path shares
+(`resolveAgentIdentity()` in
+[`src/lib/agent-identity.ts`](src/lib/agent-identity.ts); see
+`docs/architecture/cli-design.md`'s "Machine default agent — the one
+source"): first the session env `ADL_AGENT_ID_AGENT` (set by `adl run --as
+<agent>` for the whole session, or by a surface's managed default), then
+the machine's default-agent file (written by fleet reconcile from
+`manifest.json`'s `default_agent`). A tool call can't carry an inline
+per-command override, so for MCP tools the override is `adl run --as
+<agent>`. A tool call with neither source resolvable returns a normal MCP
+tool error — `no agent identity: prefix the command with
+ADL_AGENT_ID_AGENT=<agent-tarun|agent-vivek|agent-reviewer>, or start the
+session with \`adl run <surface> --as <agent>\`` — for reads and writes
+alike, never a silent fall back to a default, and the server keeps running
+for subsequent requests; it never crashes or exits on a missing identity.
+
+Once an identity is present, every call mints its own short-lived Azure DevOps access
+token by running `adl-agent-id exec --agent <agent> -- adl id token <agent> --json`
+(`adl id token` folds in the old standalone `ado-token` binary, P4; the same
+two-hop path `bin/git-ado` uses for `git`), reading the token from that child's stdout
+pipe and caching it in memory per agent until `expires_in - 60s`. The token is sent as an
+`Authorization: Bearer` header directly to `dev.azure.com` — no proxy, no CA override, and
+no Agent Vault binding held by this package. `adl-agent-id` is resolved from the global
+`PATH`, not from a repo-relative path — this server carries no assumption about running
+inside any particular checkout.
+
+## Direct CLI mode
+
+When an MCP host is unavailable, invoke the same public operations explicitly through
+`adl mcp cli …`. The command never detects an MCP failure and switches modes on
+its own. Successful commands write JSON to stdout; invalid input, a missing agent
+identity, and Azure DevOps errors write to stderr and exit nonzero.
+
+```bash
+adl mcp cli pr-list-or-get --status active
+adl mcp cli pr-create-or-update --action create \
+  --title 'feat(cli): add direct mode' \
+  --description $'## Summary\n\nAdds a CLI path.\n\n## Why\n\nMCP can be unavailable.\n\n## Changes\n\n- Add CLI mode'
+adl mcp cli build-run --id 17 --branch refs/heads/integration
+adl mcp cli workitem-create-or-update --type Bug --title 'CLI failure' --parent-id 378
+```
+
+Run `adl mcp cli --help` for the complete flag contract. The CLI has exactly the
+current MCP surface: `pr_list_or_get`, `pr_create_or_update`, `build_list_or_get`,
+`build_run`, `workitem_list_or_get`, and `workitem_create_or_update`; the CLI exposes
+their hyphenated equivalents.
+
+## Source
+
+Copied from `enact-extensions/extensions/enact-repo/tools/azure-devops/` (itself copied from
+`enact-m5`'s `.agents/tools/azure-devops/`, plus a vendored `lib/validate-pr-metadata.ts`).
+Hardcoded org/project/repo/branch values (`amsterdamdatalabs`/`Enact`/`enact-webview`/
+`integration`) are unchanged from that source.
+
+## Compiled binary behavior
+
+Both MCP and direct CLI mode invoke the Azure DevOps operations in-process through the
+shared dispatcher in [`src/tool-dispatch.ts`](src/tool-dispatch.ts). `runMcpServer()`/
+`runCli()` do nothing at import time — no `Server` instance is constructed and no handler
+is registered until they are actually called — so `apps/cli`'s static import of this
+package never starts a server as a side effect of loading `adl` for an unrelated command
+(`bun build --compile` only bundles a binary's static import graph).
+
+**`azure-devops-mcp` as a binary name is retired (W5, `docs/architecture/cli-design.md` §7 P4).** The only Azure
+DevOps surface is `adl mcp serve` / `adl mcp cli`; `azure-devops-mcp` survives only as history — in
+`workflows/scripts/fleet/fleet-retire-list.json` and `fleet-cutover.sh` (which name it in order to remove it from
+already-provisioned machines), in old plans, and in git history. It is not a build target or a test fixture name
+in this package any more. The end-to-end proof that the P4 fold survives static bundling into the real `adl`
+binary lives in `tests/compiled-adl-binary-mcp.test.ts`, which compiles `apps/cli/src/main.ts` itself and drives
+`adl mcp serve`/`adl mcp cli` from a source-free temp directory.
+
+`src/mcp-server.ts` also remains runnable standalone (`bun src/mcp-server.ts[ cli ...]`),
+unchanged, for anything not yet moved onto `adl mcp`.
+
+## Development
+
+```bash
+bun install
+bun test                                    # unit + stdio protocol tests
+bun src/mcp-server.ts                       # run directly (dev)
+```

package/packages/azdo/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@adl/azdo",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "bun src/mcp-server.ts",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.30.0"
+  },
+  "devDependencies": {
+    "@iarna/toml": "^2.2.5",
+    "@types/bun": "latest",
+    "typescript": "5.9.3",
+    "yaml": "^2.9.0"
+  }
+}