@olhapi/maestro 0.1.5-rc.11 → 0.1.5-rc.14

package/lib/install-skills.js

@@ -0,0 +1,110 @@
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const maestroSkillName = "maestro";
+
+function bundledSkillDir(baseDir = path.join(__dirname, "..")) {
+  const packagedPath = path.join(baseDir, "share", "skills", maestroSkillName);
+  if (fs.existsSync(packagedPath)) {
+    return packagedPath;
+  }
+  return path.resolve(baseDir, "..", "..", "..", "skills", maestroSkillName);
+}
+
+function bundledSkillPaths(options = {}) {
+  const fsModule = options.fs || fs;
+  const root = bundledSkillDir(options.baseDir);
+  const paths = [];
+
+  walkFiles(root, root, fsModule, (relativePath) => {
+    paths.push(relativePath);
+  });
+  return paths.sort();
+}
+
+function readBundledSkillFile(relativePath, options = {}) {
+  const fsModule = options.fs || fs;
+  return fsModule.readFileSync(path.join(bundledSkillDir(options.baseDir), relativePath));
+}
+
+function installBundledSkills(options = {}) {
+  const homeDir = options.homeDir || os.homedir();
+  const targets = options.targets || [
+    path.join(homeDir, ".agents", "skills", maestroSkillName),
+    path.join(homeDir, ".claude", "skills", maestroSkillName),
+  ];
+  const sourceRoot = bundledSkillDir(options.baseDir);
+  const fsModule = options.fs || fs;
+
+  for (const target of targets) {
+    installTree(sourceRoot, target, fsModule);
+  }
+
+  return targets;
+}
+
+function installTree(sourceRoot, dest, fsModule) {
+  const parent = path.dirname(dest);
+  fsModule.mkdirSync(parent, { recursive: true });
+
+  const tmpDir = fsModule.mkdtempSync(path.join(parent, `.${path.basename(dest)}.tmp-`));
+  try {
+    copyTree(sourceRoot, tmpDir, fsModule);
+
+    const backupDir = `${dest}.bak`;
+    fsModule.rmSync(backupDir, { force: true, recursive: true });
+    let hadBackup = false;
+    if (fsModule.existsSync(dest)) {
+      fsModule.renameSync(dest, backupDir);
+      hadBackup = true;
+    }
+
+    try {
+      fsModule.renameSync(tmpDir, dest);
+    } catch (error) {
+      if (hadBackup) {
+        try {
+          fsModule.renameSync(backupDir, dest);
+        } catch (restoreError) {
+          throw new Error(`install bundled skill: ${error.message} (failed to restore previous install: ${restoreError.message})`);
+        }
+      }
+      throw new Error(`install bundled skill: ${error.message}`);
+    }
+
+    fsModule.rmSync(backupDir, { force: true, recursive: true });
+  } finally {
+    fsModule.rmSync(tmpDir, { force: true, recursive: true });
+  }
+}
+
+function copyTree(sourceRoot, destRoot, fsModule) {
+  walkFiles(sourceRoot, sourceRoot, fsModule, (relativePath, sourcePath, stat) => {
+    const targetPath = path.join(destRoot, relativePath);
+    fsModule.mkdirSync(path.dirname(targetPath), { recursive: true });
+    const mode = stat.mode & 0o111 ? 0o755 : 0o644;
+    fsModule.writeFileSync(targetPath, fsModule.readFileSync(sourcePath), { mode });
+    fsModule.chmodSync(targetPath, mode);
+  });
+}
+
+function walkFiles(root, currentRoot, fsModule, visitor) {
+  const entries = fsModule.readdirSync(currentRoot, { withFileTypes: true });
+  for (const entry of entries) {
+    const absolutePath = path.join(currentRoot, entry.name);
+    if (entry.isDirectory()) {
+      walkFiles(root, absolutePath, fsModule, visitor);
+      continue;
+    }
+    const relativePath = path.relative(root, absolutePath);
+    visitor(relativePath, absolutePath, fsModule.statSync(absolutePath));
+  }
+}
+
+module.exports = {
+  bundledSkillDir,
+  bundledSkillPaths,
+  installBundledSkills,
+  readBundledSkillFile,
+};

package/lib/runtime-state.js

@@ -0,0 +1,82 @@
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const DEFAULT_IMAGE_REPOSITORY = "ghcr.io/olhapi/maestro";
+
+function sanitizeVersion(version) {
+  return String(version || "").trim().replace(/^v/, "");
+}
+
+function launcherDir(homeDir = os.homedir()) {
+  return path.join(homeDir, ".maestro", "launcher");
+}
+
+function runtimeStatePath(homeDir = os.homedir()) {
+  return path.join(launcherDir(homeDir), "runtime.json");
+}
+
+function imageRefForVersion(version, imageRepository = DEFAULT_IMAGE_REPOSITORY) {
+  const tag = sanitizeVersion(version);
+  if (!tag) {
+    throw new Error("image version is required");
+  }
+  return `${imageRepository}:${tag}`;
+}
+
+function readRuntimeState(options = {}) {
+  const fsModule = options.fs || fs;
+  const homeDir = options.homeDir || os.homedir();
+  const statePath = runtimeStatePath(homeDir);
+  if (!fsModule.existsSync(statePath)) {
+    return null;
+  }
+  const raw = fsModule.readFileSync(statePath, "utf8");
+  const parsed = JSON.parse(raw);
+  if (!parsed || typeof parsed !== "object" || typeof parsed.image !== "string") {
+    throw new Error(`invalid runtime state at ${statePath}`);
+  }
+  return parsed;
+}
+
+function writeRuntimeState(image, options = {}) {
+  const fsModule = options.fs || fs;
+  const homeDir = options.homeDir || os.homedir();
+  const statePath = runtimeStatePath(homeDir);
+  fsModule.mkdirSync(path.dirname(statePath), { recursive: true });
+  const payload = {
+    image,
+    updated_at: new Date().toISOString(),
+  };
+  fsModule.writeFileSync(statePath, `${JSON.stringify(payload, null, 2)}\n`);
+  return payload;
+}
+
+function resolveImageRef(options = {}) {
+  const env = options.env || process.env;
+  const runtimeState = options.runtimeState === undefined ? readRuntimeState(options) : options.runtimeState;
+  const packageVersion = sanitizeVersion(options.packageVersion);
+  const imageRepository = options.imageRepository || DEFAULT_IMAGE_REPOSITORY;
+
+  if (typeof env.MAESTRO_IMAGE === "string" && env.MAESTRO_IMAGE.trim() !== "") {
+    return env.MAESTRO_IMAGE.trim();
+  }
+  if (runtimeState && typeof runtimeState.image === "string" && runtimeState.image.trim() !== "") {
+    return runtimeState.image.trim();
+  }
+  if (!packageVersion) {
+    throw new Error("package version is required to resolve the default runtime image");
+  }
+  return imageRefForVersion(packageVersion, imageRepository);
+}
+
+module.exports = {
+  DEFAULT_IMAGE_REPOSITORY,
+  imageRefForVersion,
+  launcherDir,
+  readRuntimeState,
+  resolveImageRef,
+  runtimeStatePath,
+  sanitizeVersion,
+  writeRuntimeState,
+};

package/package.json

@@ -1,24 +1,28 @@
 {
   "name": "@olhapi/maestro",
-  "version": "0.1.5-rc.11",
-  "description": "Maestro CLI packaged for global npm installation",
+  "version": "0.1.5-rc.14",
+  "description": "Maestro Docker-backed launcher for global npm installation",
   "license": "MIT",
+  "engines": {
+    "node": ">=24"
+  },
   "bin": {
-    "maestro": "bin/maestro.js"
+    "maestro": "bin/maestro"
   },
   "files": [
+    "bin/maestro",
+    "bin/maestro.cmd",
+    "bin/maestro.ps1",
     "bin/maestro.js",
-    "lib/get-exe-path.js",
+    "lib/browser.js",
+    "lib/cli.js",
+    "lib/docker-plan.js",
+    "lib/install-skills.js",
+    "lib/runtime-state.js",
+    "share/skills/maestro",
     "LICENSE",
     "README.md"
   ],
-  "optionalDependencies": {
-    "@olhapi/maestro-darwin-arm64": "0.1.5-rc.11",
-    "@olhapi/maestro-darwin-x64": "0.1.5-rc.11",
-    "@olhapi/maestro-linux-x64-gnu": "0.1.5-rc.11",
-    "@olhapi/maestro-linux-arm64-gnu": "0.1.5-rc.11",
-    "@olhapi/maestro-win32-x64": "0.1.5-rc.11"
-  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/olhapi/maestro.git"

package/share/skills/maestro/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: maestro
+description: Use Maestro to initialize workflows, run the local loop, bridge MCP, and manage projects, epics, issues, and readiness checks.
+---
+
+# Maestro CLI Skill
+
+Use this skill when a task involves Maestro's local orchestration flow, repo setup, queue management, or readiness checks.
+
+## Prefer Maestro when
+
+- You need to create or refresh `WORKFLOW.md`.
+- You want to start or supervise the local daemon.
+- You need to connect another agent to the live queue through MCP.
+- You are creating, updating, moving, or inspecting projects, epics, or issues.
+- You want to verify repo readiness before launch.
+
+## Start with the smallest command that fits
+
+- `maestro workflow init .` for repo bootstrap.
+- `maestro run` for the local loop and dashboard.
+- `maestro mcp` only after the daemon is already running.
+- `maestro verify`, `maestro doctor`, or `maestro spec-check` for readiness and validation.
+
+## Common flows
+
+- Setup and launch: see [setup](references/setup.md)
+- Day-to-day operations: see [operations](references/operations.md)
+- Projects and issues: see [project-work](references/project-work.md)
+- Readiness checks: see [readiness](references/readiness.md)
+
+## Working style
+
+- Prefer exact, repo-local commands over generic advice.
+- Keep changes scoped to the issue or project being worked.
+- Use `--json` when the output will feed another tool or agent.
+- Reuse the live daemon and existing workflow file before inventing a new setup.
+

package/share/skills/maestro/references/operations.md

@@ -0,0 +1,21 @@
+# Operations
+
+Use these commands when the daemon is running and you want to inspect or steer live work.
+
+## Status and runtime
+
+```bash
+maestro status
+maestro status --dashboard --api-url http://127.0.0.1:8787
+maestro sessions --api-url http://127.0.0.1:8787
+maestro events --api-url http://127.0.0.1:8787
+maestro runtime-series --api-url http://127.0.0.1:8787
+```
+
+## When to use
+
+- Use `status` for a quick health check.
+- Use `sessions` when multiple runs are in flight.
+- Use `events` when you need a recent timeline of what happened.
+- Use `runtime-series` when you need token or activity trends over time.
+

package/share/skills/maestro/references/project-work.md

@@ -0,0 +1,44 @@
+# Projects and issues
+
+Use these commands for the local queue and issue lifecycle.
+
+## Projects
+
+```bash
+maestro project create <name> --repo <repo_path>
+maestro project list
+maestro project show <id>
+maestro project update <id>
+maestro project delete <id>
+```
+
+## Epics
+
+```bash
+maestro epic create <name> --project <project_id>
+maestro epic list
+maestro epic show <id>
+maestro epic update <id>
+maestro epic delete <id>
+```
+
+## Issues
+
+```bash
+maestro issue create <title>
+maestro issue list
+maestro issue show <identifier>
+maestro issue update <identifier>
+maestro issue move <identifier> <state>
+maestro issue block <identifier> <blocker_identifier...>
+maestro issue unblock <identifier> <blocker_identifier...>
+maestro issue comments list <identifier>
+maestro issue assets add <identifier> <path>
+```
+
+## Guidance
+
+- Use `--project` and labels to keep work scoped.
+- Use `move` when you need to change queue state, not when you only want to update metadata.
+- Use comments and assets for review context rather than burying details in the issue title.
+

package/share/skills/maestro/references/readiness.md

@@ -0,0 +1,18 @@
+# Readiness
+
+Use these commands before launch or when the repo needs a sanity check.
+
+## Validation commands
+
+```bash
+maestro verify
+maestro doctor
+maestro spec-check
+```
+
+## Guidance
+
+- Use `verify` when you want the normal readiness check and remediation guidance.
+- Use `doctor` when you want the same checks with a different presentation.
+- Use `spec-check` when you want a read-only validation pass.
+

package/share/skills/maestro/references/setup.md

@@ -0,0 +1,45 @@
+# Setup
+
+Use these commands when you are preparing a repo or teaching another agent how to connect to Maestro.
+
+## Bundle install
+
+Install the Maestro skill bundle into the current user's personal skill directories:
+
+```bash
+maestro install --skills
+```
+
+The installer writes the skill to:
+
+- `~/.agents/skills/maestro` for Codex
+- `~/.claude/skills/maestro` for Claude Code
+
+## Workflow bootstrap
+
+Create or refresh the repo contract:
+
+```bash
+maestro workflow init .
+```
+
+Use `--defaults` when you want the non-interactive scaffold. Use `--force` only when overwriting an existing file is intentional.
+
+## Launch the loop
+
+Start the daemon after the workflow file is in place:
+
+```bash
+maestro run
+```
+
+## Attach MCP
+
+Bridge the live daemon over stdio for a connected coding agent:
+
+```bash
+maestro mcp
+```
+
+Start `maestro run` first, then point the agent at the same database.
+

package/lib/get-exe-path.js

@@ -1,118 +0,0 @@
-const fs = require("node:fs");
-const path = require("node:path");
-
-const supportedTargets = Object.freeze({
-  "darwin:arm64": {
-    packageName: "@olhapi/maestro-darwin-arm64",
-    label: "darwin/arm64",
-  },
-  "darwin:x64": {
-    packageName: "@olhapi/maestro-darwin-x64",
-    label: "darwin/x64",
-  },
-  "linux:x64": {
-    packageName: "@olhapi/maestro-linux-x64-gnu",
-    label: "linux/x64 (glibc)",
-  },
-  "linux:arm64": {
-    packageName: "@olhapi/maestro-linux-arm64-gnu",
-    label: "linux/arm64 (glibc)",
-  },
-  "win32:x64": {
-    packageName: "@olhapi/maestro-win32-x64",
-    label: "win32/x64",
-  },
-});
-
-function resolveTarget(platform, arch) {
-  return supportedTargets[`${platform}:${arch}`] ?? null;
-}
-
-function supportedTargetSummary() {
-  return Object.values(supportedTargets)
-    .map((target) => target.label)
-    .join(", ");
-}
-
-function readProcessReport() {
-  if (!process.report || typeof process.report.getReport !== "function") {
-    return null;
-  }
-  try {
-    return process.report.getReport();
-  } catch {
-    return null;
-  }
-}
-
-function hasGlibcRuntime(report) {
-  const version = report && report.header && report.header.glibcVersionRuntime;
-  return typeof version === "string" && version.trim() !== "";
-}
-
-function buildInstallError(platform, arch, expectedPackageName, report) {
-  const parts = [
-    `Maestro npm install supports ${supportedTargetSummary()}.`,
-    `Could not resolve a packaged binary for ${platform}/${arch}.`,
-  ];
-  if (expectedPackageName) {
-    parts.push(`Expected package: ${expectedPackageName}.`);
-  }
-  if (platform === "linux") {
-    if (!hasGlibcRuntime(report)) {
-      parts.push("Linux npm packages currently target glibc only. Alpine and other musl-based distros should build from source or use Docker.");
-    } else {
-      parts.push("If your install is on glibc Linux, reinstalling can restore a missing optional dependency. Alpine and other musl-based distros should build from source or use Docker.");
-    }
-  } else {
-    parts.push("If your platform is unsupported, build from source or use Docker.");
-  }
-  return parts.join(" ");
-}
-
-function resolveExePath(options = {}) {
-  const platform = options.platform ?? process.platform;
-  const arch = options.arch ?? process.arch;
-  const pathModule = options.pathModule ?? path;
-  const resolvePackageJson =
-    options.resolvePackageJson ??
-    ((packageName) => require.resolve(`${packageName}/package.json`));
-  const existsSync = options.existsSync ?? fs.existsSync;
-  const report = options.report ?? readProcessReport();
-
-  const target = resolveTarget(platform, arch);
-  if (!target) {
-    throw new Error(buildInstallError(platform, arch, null, report));
-  }
-
-  let packageJsonPath;
-  try {
-    packageJsonPath = resolvePackageJson(target.packageName);
-  } catch {
-    throw new Error(buildInstallError(platform, arch, target.packageName, report));
-  }
-
-  let exePath = pathModule.join(
-    pathModule.dirname(packageJsonPath),
-    "lib",
-    platform === "win32" ? "maestro.exe" : "maestro",
-  );
-  if (platform === "win32" && exePath.length >= 248 && !exePath.startsWith("\\\\?\\")) {
-    exePath = `\\\\?\\${exePath}`;
-  }
-  if (!existsSync(exePath)) {
-    throw new Error(`Executable not found in ${target.packageName}: ${exePath}`);
-  }
-  return exePath;
-}
-
-function getExePath() {
-  return resolveExePath();
-}
-
-module.exports = {
-  buildInstallError,
-  getExePath,
-  resolveExePath,
-  resolveTarget,
-};