@ankhorage/orchestrator 0.1.1 → 0.2.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Ankhorage
+Copyright (c) 2026 ankhorage
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,139 +1,36 @@
-# @ankhorage/orchestrator
+# orchestrator
 
-`@ankhorage/orchestrator` is the standalone engine extracted and redesigned from the relevant contract and execution concepts in `../ankhorage4/packages/plugin-kit` and the CLI runtime helpers.
+A declarative installation engine for managing project modules.
 
-The package has one job: execute module plans against a project root, track the applied work in `.ankh/ledger/<moduleId>.json`, and reverse that work deterministically on removal.
+## 🎯 What you get
 
-## Architecture
+- Install features like modules
+- Remove them without breaking your app
+- No manual file editing
 
-- Orchestrator: owns the loaded module registry, resolves dependencies, installs modules, removes modules, and writes the ledger.
-- Modules: pure planners that return actions from `plan(ctx)`.
-- Host: loads module definitions, gathers config, and triggers `installModule` / `removeModule`.
+## ✨ Features
 
-The orchestrator does not know templates, UI, Studio, Expo layout generation, or runtime-specific behavior.
+- Deterministic install/uninstall
+- Dependency-aware execution
 
-## Public API
+## 🚀 Installation
 
-```ts
-import { createOrchestrator, defineModule } from "@ankhorage/orchestrator";
-
-const localizationModule = defineModule({
-  id: "expo-localization",
-  dependencies: ["base-i18n"],
-  async plan(ctx) {
-    return [
-      {
-        type: "write-files",
-        files: [
-          {
-            path: "src/modules/localization/index.ts",
-            content: "export const ready = true;\n",
-            overwrite: true,
-          },
-        ],
-      },
-    ];
-  },
-});
-
-const orchestrator = createOrchestrator({
-  modules: [localizationModule],
-  projectRoot: "/absolute/path/to/project",
-});
-
-await orchestrator.installModule("expo-localization", {
-  config: { defaultLocale: "en" },
-});
-
-await orchestrator.removeModule("expo-localization");
+```bash
+bun add @ankhorage/orchestrator
 ```
 
-### Module contract
+## 📦 Usage
 
 ```ts
-defineModule({
-  id: string,
-  version?: string,
-  dependencies?: string[],
-  plan(ctx): ModuleAction[] | Promise<ModuleAction[]>
-})
-```
-
-`plan(ctx)` receives:
-
-- `projectRoot`
-- `moduleId`
-- `config`
-
-The host only passes `config`; the orchestrator injects the rest.
-
-### Supported actions
-
-V1 supports exactly these actions:
-
-- `ensure-packages`
-- `write-files`
-- `json-set`
-- `patch-text-block`
-
-Package execution is internal infrastructure only. The orchestrator uses safe `bun add` / `bun remove` argument arrays under `src/fs/exec.ts` and does not expose an adapter API.
-
-## Ledger behavior
-
-Each installed module writes `.ankh/ledger/<moduleId>.json`.
-
-Every ledger entry stores:
-
-- `moduleId`
-- `moduleVersion`
-- `installedAt`
-- `config`
-- `dependencies`
-- `actions`
-- `applied`
-
-The `applied` section is the source of truth for rollback. Removal never recomputes a module plan.
-
-## Install and remove semantics
-
-- Dependency resolution belongs to the orchestrator, not the host.
-- Missing declared dependencies fail the install before any execution starts.
-- Dependencies are installed before the requested module.
-- Removal is immediate. The orchestrator reads the ledger, replays rollback operations, and deletes the ledger file.
-- Removal is blocked if another installed module still depends on the target module.
-
-### Replace-style reinstall
-
-If `installModule()` is called for a module that is already installed, the orchestrator removes the existing installed state first and then runs the new plan.
-
-This behavior is intentional in v1 and has an important consequence:
-
-- if the reinstall fails after the prior state was removed, the module remains removed
-
-Fresh installs behave differently:
-
-- if a fresh install fails part-way through, the orchestrator rolls back the new partial work and leaves no orchestrator-managed residue behind
-
-## Development
-
-This repo uses:
-
-- `@ankhorage/devtools` for lint and prettier alignment
-- `@changesets/cli` for versioning
-
-Run the quality gates with:
-
-```sh
-bun install
-bun run build
-bun run lint
-bun run test
-bunx knip
+orchestrator.install("expo-localization");
+orchestrator.uninstall("expo-localization");
 ```
 
-## Repo-switch rule
+## 🧪 Use Cases
 
-Work in this repo stops once the orchestrator package is release-ready.
+- Feature-based app composition
+- Safe project scaffolding
 
-Module extraction must happen later in dedicated repos such as `@ankhorage/orchestrator-module-expo-localization`. When that work starts, the current repo is no longer the right place to continue. The next step must be an explicit repository switch request before any module-repo changes are made.
+## 🧠 Why this exists
 
+Typical tools are one-way. This system enables reversible, structured changes.

package/package.json

@@ -1,9 +1,18 @@
 {
   "name": "@ankhorage/orchestrator",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "type": "module",
+  "license": "MIT",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ankhorage/orchestrator.git"
+  },
+  "homepage": "https://github.com/ankhorage/orchestrator#readme",
+  "bugs": {
+    "url": "https://github.com/ankhorage/orchestrator/issues"
+  },
   "files": [
     "dist"
   ],
@@ -22,19 +31,19 @@
     "test": "bun test",
     "knip": "bunx knip",
     "changeset": "changeset",
-    "changeset:version": "changeset version"
+    "version-packages": "changeset version"
   },
   "devDependencies": {
-    "@ankhorage/devtools": "^1.0.0",
-    "@changesets/cli": "^2.30.0",
-    "@types/bun": "^1.3.8",
-    "@types/node": "^25.2.3",
-    "eslint": "^10.2.0",
-    "knip": "^5.83.1",
-    "prettier": "^3.8.1",
+    "@ankhorage/devtools": "^1.0.1",
+    "@changesets/cli": "^2.31.0",
+    "@types/bun": "^1.3.13",
+    "@types/node": "^25.6.0",
+    "eslint": "^10.2.1",
+    "knip": "^5.88.1",
+    "prettier": "^3.8.3",
     "typescript": "^5.9.3"
   },
-  "packageManager": "bun@1.3.11",
+  "packageManager": "bun@1.3.13",
   "publishConfig": {
     "access": "public"
   }