@alexey_platkovsky/taskpilot 0.1.0-beta.1

package/bin/taskpilot

@@ -0,0 +1,454 @@
+#!/usr/bin/env node
+
+/**
+ * TaskPilot npm entry point.
+ *
+ * Discovers a compatible Python >=3.11 interpreter, manages a user-cache
+ * runtime environment, and delegates CLI commands to the bundled Python
+ * implementation.
+ *
+ * Handled inline (no delegation):
+ *   taskpilot --version
+ *   taskpilot doctor --rebuild-runtime
+ *
+ * All other commands are forwarded to Python with TASKPILOT_WEB_DIST set.
+ */
+
+const { execSync, spawn } = require("child_process");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const packageJson = require("../package.json");
+
+// ---------------------------------------------------------------------------
+// T3: Python discovery
+// ---------------------------------------------------------------------------
+
+/**
+ * @returns {string} The resolved Python command path.
+ */
+function discoverPython() {
+  const override = process.env.TASKPILOT_PYTHON;
+  if (override) {
+    validatePython(override);
+    return override;
+  }
+
+  const candidates = process.platform === "win32"
+    ? ["python3", "python", "python3.14", "python3.13", "python3.12", "python3.11"]
+    : ["python3", "python", "python3.14", "python3.13", "python3.12", "python3.11"];
+  const errors = [];
+
+  for (const cmd of candidates) {
+    try {
+      validatePython(cmd, { fatal: false });
+      return cmd;
+    } catch (err) {
+      errors.push(err.message);
+    }
+  }
+
+  fail(
+    "Could not find a compatible Python interpreter.\n" +
+    "Install Python >=3.11 with venv and pip, or set TASKPILOT_PYTHON to\n" +
+    "the full path of a compatible Python executable." +
+    (errors.length ? "\nChecked candidates:\n- " + errors.join("\n- ") : "")
+  );
+}
+
+function validatePython(pythonCmd, options = {}) {
+  const fatal = options.fatal !== false;
+  function invalid(message) {
+    if (fatal) {
+      fail(message);
+    }
+    throw new Error(message);
+  }
+
+  let version;
+  try {
+    version = execSync(`"${pythonCmd}" -c "import sys; print(sys.version)"`, {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+    }).trim();
+  } catch {
+    invalid(`${pythonCmd}: failed to run Python. Check that it is a valid Python executable.`);
+  }
+
+  const match = version.match(/^(\d+)\.(\d+)/);
+  if (!match) {
+    invalid(`${pythonCmd}: could not determine Python version (output: ${version})`);
+  }
+
+  const major = parseInt(match[1], 10);
+  const minor = parseInt(match[2], 10);
+
+  if (major < 3 || (major === 3 && minor < 11)) {
+    invalid(
+      `${pythonCmd}: Python ${major}.${minor} is too old.\n` +
+      "TaskPilot requires Python >=3.11. Install a newer Python or set\n" +
+      "TASKPILOT_PYTHON to a compatible interpreter."
+    );
+  }
+
+  // Validate venv
+  try {
+    execSync(`"${pythonCmd}" -m venv --help`, {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+  } catch {
+    invalid(
+      `${pythonCmd}: missing venv module.\n` +
+      "Install the venv module for your Python distribution\n" +
+      "(e.g. 'python3 -m ensurepip && python3 -m pip install virtualenv'\n" +
+      "or install 'python3-venv' via your system package manager)."
+    );
+  }
+
+  // Validate pip (ensurepip bootstraps pip, check it's available)
+  try {
+    execSync(`"${pythonCmd}" -m pip --version`, {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+  } catch {
+    invalid(
+      `${pythonCmd}: missing pip.\n` +
+      "Run 'python3 -m ensurepip' or install pip for your Python distribution."
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// T4: Runtime cache
+// ---------------------------------------------------------------------------
+
+/**
+ * Get the Python major.minor version string.
+ */
+function getPythonVersion(pythonCmd) {
+  const output = execSync(
+    `"${pythonCmd}" -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')"`,
+    { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }
+  ).trim();
+  return output;
+}
+
+/**
+ * Get the base cache directory for TaskPilot runtimes.
+ * Uses XDG/standard cache locations per platform.
+ */
+function getCacheDir() {
+  if (process.platform === "win32") {
+    const localAppData = process.env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local");
+    return path.join(localAppData, "taskpilot", "Cache");
+  }
+  if (process.platform === "darwin") {
+    return path.join(os.homedir(), "Library", "Caches", "taskpilot");
+  }
+  const xdg = process.env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache");
+  return path.join(xdg, "taskpilot");
+}
+
+/**
+ * Get the versioned runtime path.
+ * Keyed by npm version and Python major.minor version.
+ */
+function getRuntimePath(npmVersion, pythonVersion) {
+  return path.join(getCacheDir(), "runtimes", `npm-${npmVersion}`, `py${pythonVersion}`);
+}
+
+// ---------------------------------------------------------------------------
+// T5: Dependency installation
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the path to the Python executable inside a venv.
+ */
+function venvPython(runtimePath) {
+  if (process.platform === "win32") {
+    return path.join(runtimePath, "Scripts", "python.exe");
+  }
+  return path.join(runtimePath, "bin", "python");
+}
+
+/**
+ * Ensure the runtime venv is ready.
+ * Returns the path to the venv Python executable.
+ */
+function ensureRuntime(pythonCmd, runtimePath) {
+  const venvPy = venvPython(runtimePath);
+
+  if (fs.existsSync(venvPy)) {
+    // Quick health check: can the venv import a key dependency?
+    try {
+      execSync(`"${venvPy}" -c "import fastapi"`, {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+      process.stderr.write(`taskpilot: using cached runtime at ${runtimePath}\n`);
+      return venvPy;
+    } catch {
+      process.stderr.write("taskpilot: cached runtime is corrupted, rebuilding...\n");
+      deletePartialCache(runtimePath);
+    }
+  }
+
+  // --- acquire lock to prevent concurrent venv creation ---
+  const lockFile = runtimePath + ".lock";
+  try {
+    fs.mkdirSync(runtimePath, { recursive: true });
+    fs.mkdirSync(lockFile);
+  } catch (err) {
+    if (err.code === "EEXIST") {
+      if (!fs.existsSync(lockFile)) {
+        // runtimePath itself exists but lockFile doesn't — retry as top-level
+        return ensureRuntime(pythonCmd, runtimePath);
+      }
+      // Lock exists — poll until released (do NOT rmdir — it may belong to the owner)
+      process.stderr.write("taskpilot: waiting for another setup to finish...\n");
+      const deadline = Date.now() + 120000; // 2 minutes
+      while (fs.existsSync(lockFile)) {
+        if (Date.now() >= deadline) {
+          fail("Timed out waiting for runtime setup. Try again or run: taskpilot doctor --rebuild-runtime");
+        }
+        const spinEnd = Date.now() + 500;
+        while (Date.now() < spinEnd) { /* poll interval */ }
+      }
+      // Lock released — check if venv is now ready
+      if (fs.existsSync(venvPy)) {
+        try {
+          execSync(`"${venvPy}" -c "import fastapi"`, {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+          });
+          process.stderr.write(`taskpilot: using cached runtime at ${runtimePath}\n`);
+          return venvPy;
+        } catch {
+          // Corrupted — fall through to rebuild it
+          process.stderr.write("taskpilot: cached runtime is corrupted, rebuilding...\n");
+          deletePartialCache(runtimePath);
+        }
+      }
+      // Re-acquire lock and rebuild
+      try { fs.mkdirSync(lockFile); } catch { return ensureRuntime(pythonCmd, runtimePath); }
+    } else {
+      fail(`Failed to create runtime directory at ${runtimePath}: ${err.message}`);
+    }
+  }
+
+  // Release lock on exit/failure
+  function releaseLock() {
+    try { fs.rmdirSync(lockFile); } catch {}
+  }
+
+  process.stderr.write("taskpilot: setting up Python runtime (first run)...\n");
+
+  // --- create venv ---
+  process.stderr.write("taskpilot: creating virtual environment...\n");
+  try {
+    execSync(`"${pythonCmd}" -m venv "${runtimePath}"`, {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+  } catch (err) {
+    deletePartialCache(runtimePath);
+    releaseLock();
+    fail(
+      `Failed to create virtual environment at ${runtimePath}\n` +
+      `Cause: ${err.stderr || err.message}`
+    );
+  }
+
+  // --- install dependencies ---
+  process.stderr.write("taskpilot: installing dependencies...\n");
+
+  const packageDir = path.resolve(__dirname, "..");
+  const reqLock = path.join(packageDir, "requirements.lock");
+
+  if (!fs.existsSync(reqLock)) {
+    deletePartialCache(runtimePath);
+    releaseLock();
+    fail(`Bundled requirements.lock not found at ${reqLock}. Package may be incomplete.`);
+  }
+
+  const setupLog = path.join(runtimePath, "setup.log");
+
+  try {
+    execSync(
+      `"${venvPy}" -m pip install -r "${reqLock}" --quiet --no-input --log "${setupLog}"`,
+      {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+        timeout: 300000,
+      }
+    );
+  } catch (err) {
+    const failureLog = runtimePath + ".setup.log";
+    const tail = copySetupLogAndTail(setupLog, failureLog);
+    deletePartialCache(runtimePath);
+    releaseLock();
+
+    const isOffline =
+      (err.stderr || "").includes("Could not connect") ||
+      (err.stderr || "").includes("Failed to establish") ||
+      (err.stderr || "").includes("Name or service not known") ||
+      (err.stderr || "").includes("Network is unreachable") ||
+      tail.includes("Could not connect") ||
+      tail.includes("Failed to establish");
+
+    let instructions = "";
+    if (isOffline) {
+      instructions =
+        "\n\nSetup requires network access to install Python dependencies.\n" +
+        "Connect to the internet and try again.";
+    } else {
+      instructions =
+        "\n\nCheck the setup log for details: " + failureLog + "\n" +
+        "You can retry by running: taskpilot doctor --rebuild-runtime";
+    }
+
+    fail(
+      `Dependency installation failed.\n` +
+      `Setup log: ${failureLog}\n` +
+      `--- pip output (last lines) ---\n${tail}\n` +
+      `--- end pip output ---` +
+      instructions
+    );
+  }
+
+  releaseLock();
+  process.stderr.write("taskpilot: runtime ready\n");
+  return venvPy;
+}
+
+function copySetupLogAndTail(setupLog, failureLog) {
+  try {
+    fs.copyFileSync(setupLog, failureLog);
+    const logContent = fs.readFileSync(failureLog, "utf8");
+    const lines = logContent.trim().split("\n");
+    return lines.slice(-40).join("\n");
+  } catch {
+    return "(setup log unavailable)";
+  }
+}
+
+/**
+ * Delete the partial runtime cache directory.
+ * Does not remove unrelated caches.
+ */
+function deletePartialCache(runtimePath) {
+  if (fs.existsSync(runtimePath)) {
+    try {
+      fs.rmSync(runtimePath, { recursive: true, force: true });
+      process.stderr.write("taskpilot: removed partial cache\n");
+    } catch (err) {
+      process.stderr.write(`taskpilot: warning: could not remove partial cache at ${runtimePath}: ${err.message}\n`);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Command handling
+// ---------------------------------------------------------------------------
+
+function fail(message) {
+  process.stderr.write(`taskpilot: ${message}\n`);
+  process.exit(1);
+}
+
+function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 1 && args[0] === "--version") {
+    process.stdout.write(`${packageJson.version}\n`);
+    process.exit(0);
+  }
+
+  if (args.length >= 1 && args[0] === "doctor" && args.includes("--rebuild-runtime")) {
+    const python = discoverPython();
+    const pyVersion = getPythonVersion(python);
+    const runtimePath = getRuntimePath(packageJson.version, pyVersion);
+
+    process.stderr.write(`taskpilot: rebuilding runtime for ${pyVersion}...\n`);
+    deletePartialCache(runtimePath);
+    ensureRuntime(python, runtimePath);
+    process.stderr.write("taskpilot: runtime rebuilt successfully\n");
+    process.exit(0);
+  }
+
+  // --- resolve python ---
+  const python = discoverPython();
+  const pyVersion = getPythonVersion(python);
+  const runtimePath = getRuntimePath(packageJson.version, pyVersion);
+
+  // --- ensure runtime is ready ---
+  const venvPy = ensureRuntime(python, runtimePath);
+
+  // --- resolve WebUI assets path ---
+  const packageDir = path.resolve(__dirname, "..");
+  const webDist = path.join(packageDir, "web-dist");
+
+  // --- delegate to Python ---
+  delegateToPython(venvPy, webDist, args);
+}
+
+// ---------------------------------------------------------------------------
+// T7: Delegate to Python
+// ---------------------------------------------------------------------------
+
+/**
+ * Forward all arguments to the bundled Python implementation.
+ * Sets TASKPILOT_WEB_DIST to the staged WebUI assets directory.
+ * Forwards exit code and signals.
+ */
+function delegateToPython(venvPy, webDist, args) {
+  const packageDir = path.resolve(__dirname, "..");
+  const srcDir = path.join(packageDir, "src");
+
+  const child = spawn(
+    venvPy,
+    ["-m", "taskpilot.cli.app", ...args],
+    {
+      stdio: "inherit",
+      env: {
+        ...process.env,
+        TASKPILOT_WEB_DIST: webDist,
+        PYTHONPATH: srcDir,
+      },
+    }
+  );
+
+  const signalHandlers = {};
+  const sigs = process.platform === "win32"
+    ? ["SIGINT", "SIGTERM"]
+    : ["SIGINT", "SIGTERM", "SIGHUP"];
+
+  child.on("error", (err) => {
+    fail(`Failed to launch Python (${venvPy}): ${err.message}`);
+  });
+
+  child.on("close", (code, signal) => {
+    // Remove signal listeners
+    sigs.forEach((sig) => {
+      process.removeListener(sig, signalHandlers[sig]);
+    });
+
+    if (signal) {
+      // Child was killed by a signal; exit with convention 128+N
+      const sigNum = { SIGINT: 2, SIGTERM: 15, SIGHUP: 1 }[signal] || 1;
+      process.exit(128 + sigNum);
+    }
+    process.exit(code || 0);
+  });
+
+  sigs.forEach((sig) => {
+    const handler = () => child.kill(sig);
+    signalHandlers[sig] = handler;
+    process.on(sig, handler);
+  });
+}
+
+main();

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@alexey_platkovsky/taskpilot",
+  "version": "0.1.0-beta.1",
+  "description": "Local-first, file-based task management. Markdown/YAML files are the source of truth.",
+  "license": "SEE LICENSE IN LICENSE",
+  "bin": {
+    "taskpilot": "bin/taskpilot"
+  },
+  "files": [
+    "bin/taskpilot",
+    "src/",
+    "web-dist/",
+    "requirements.lock",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "preflight": "bash scripts/release/preflight.sh",
+    "build:staging": "bash scripts/release/build-staging.sh",
+    "quality-gates": "bash scripts/release/quality-gates.sh",
+    "release:dry-run": "bash scripts/release/publish.sh --dry-run",
+    "release:publish": "bash scripts/release/publish.sh --publish",
+    "release": "npm run preflight && npm run quality-gates && npm run release:dry-run && npm run release:publish"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/anomalyco/task-pilot.git"
+  },
+  "private": false
+}

package/requirements.lock

@@ -0,0 +1,66 @@
+# This file was autogenerated by uv via the following command:
+#    uv pip compile pyproject.toml -o requirements.lock
+annotated-doc==0.0.4
+    # via
+    #   fastapi
+    #   typer
+annotated-types==0.7.0
+    # via pydantic
+anyio==4.14.1
+    # via
+    #   starlette
+    #   watchfiles
+click==8.4.2
+    # via uvicorn
+fastapi==0.138.2
+    # via taskpilot (pyproject.toml)
+h11==0.16.0
+    # via uvicorn
+httptools==0.8.0
+    # via uvicorn
+idna==3.18
+    # via anyio
+markdown-it-py==4.2.0
+    # via rich
+mdurl==0.1.2
+    # via markdown-it-py
+pydantic==2.13.4
+    # via
+    #   taskpilot (pyproject.toml)
+    #   fastapi
+pydantic-core==2.46.4
+    # via pydantic
+pygments==2.20.0
+    # via rich
+python-dotenv==1.2.2
+    # via uvicorn
+pyyaml==6.0.3
+    # via
+    #   taskpilot (pyproject.toml)
+    #   uvicorn
+rich==15.0.0
+    # via typer
+shellingham==1.5.4
+    # via typer
+starlette==1.3.1
+    # via fastapi
+typer==0.26.8
+    # via taskpilot (pyproject.toml)
+typing-extensions==4.15.0
+    # via
+    #   fastapi
+    #   pydantic
+    #   pydantic-core
+    #   typing-inspection
+typing-inspection==0.4.2
+    # via
+    #   fastapi
+    #   pydantic
+uvicorn==0.49.0
+    # via taskpilot (pyproject.toml)
+uvloop==0.22.1 ; sys_platform != "win32"
+    # via uvicorn
+watchfiles==1.2.0
+    # via uvicorn
+websockets==16.0
+    # via uvicorn

package/src/taskpilot/__init__.py

@@ -0,0 +1 @@
+"""TaskPilot — local-first, file-based task management core."""

package/src/taskpilot/cli/__init__.py

@@ -0,0 +1,6 @@
+"""TaskPilot CLI adapter (feature F003).
+
+This package is an *adapter*: it translates command-line input into calls on the
+F002 domain services and renders their results as human text or deterministic
+JSON. It owns no domain rules — those live in :mod:`taskpilot.services`.
+"""

package/src/taskpilot/cli/app.py

@@ -0,0 +1,61 @@
+"""TaskPilot CLI entry point and root Typer app (task F003-T1, requirement F003-R8).
+
+Defines the root ``taskpilot`` command group and its global ``--json`` option.
+Subcommands (``init``, ``project``, ``item``, ``validate``, ``serve``) are
+registered onto :data:`app` by their own modules in later F003 tasks. The
+console-script entry point in ``pyproject.toml`` points at :data:`app`.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from taskpilot.cli.context import CLIState
+
+__all__ = ["app"]
+
+app = typer.Typer(
+    name="taskpilot",
+    help="TaskPilot — local-first, file-based task management.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    json: bool = typer.Option(
+        False,
+        "--json",
+        help="Emit machine-readable JSON to stdout instead of human-readable text.",
+    ),
+) -> None:
+    """Resolve global options once and store them for every subcommand."""
+    ctx.obj = CLIState(json=json)
+
+
+def _register_commands() -> None:
+    """Attach every command module to :data:`app`.
+
+    Imported here (not at module top) so command modules can import from this
+    module without a circular import.
+    """
+    from taskpilot.cli.commands import init as init_cmd
+    from taskpilot.cli.commands import item as item_cmd
+    from taskpilot.cli.commands import project as project_cmd
+    from taskpilot.cli.commands import serve as serve_cmd
+    from taskpilot.cli.commands import validate as validate_cmd
+
+    init_cmd.register(app)
+    project_cmd.register(app)
+    item_cmd.register(app)
+    validate_cmd.register(app)
+    serve_cmd.register(app)
+
+
+_register_commands()
+
+
+if __name__ == "__main__":  # pragma: no cover - manual invocation convenience
+    app()

package/src/taskpilot/cli/commands/__init__.py

@@ -0,0 +1,6 @@
+"""Command modules for the TaskPilot CLI (feature F003).
+
+Each module defines a command (or command group) and a ``register(app)`` hook;
+:mod:`taskpilot.cli.app` calls every hook so commands attach without importing
+the root app (avoiding a circular import).
+"""