@ankhorage/devtools 1.8.4 → 1.9.0

package/dist/tools/skills/assets/ankhorage-project-structure/references/cli.md

@@ -0,0 +1,117 @@
+# Ankhorage Package CLI
+
+An Ankhorage package may expose one package-level Ankh command provider under `src/cli/`. The
+package is the CLI ownership boundary.
+
+Do not create `cli/` directories inside internal domains. An independently bound package owns its
+own package-level `src/cli/` and release lifecycle.
+
+## Command tree
+
+The filesystem below `src/cli/commands/` mirrors the public command path after the package prefix.
+
+```text
+ankh <package> <segment> ... <command>
+  -> src/cli/commands/<segment>/.../<command>.ts
+```
+
+Examples:
+
+```text
+ankh studio dev
+  -> src/cli/commands/dev.ts
+
+ankh studio projects list
+  -> src/cli/commands/projects/list.ts
+
+ankh studio projects create --name Shop
+  -> src/cli/commands/projects/create.ts
+
+ankh deploy release inspect
+  -> src/cli/commands/release/inspect.ts
+```
+
+The package prefix is represented by the provider and is not repeated under `commands/`. Flags and
+positional arguments do not affect the directory tree.
+
+Bad:
+
+```text
+src/cli/commands/studio/projects/list.ts
+src/cli/commands/listProjects.ts
+src/projects/cli/list.ts
+```
+
+Good:
+
+```text
+src/cli/commands/projects/list.ts
+```
+
+## Layout
+
+```text
+src/
+  cli/
+    index.ts
+    commands/
+      <command>.ts
+      <group>/
+        <command>.ts
+```
+
+`src/cli/index.ts` owns provider identity, category, capabilities, command definitions, handler
+registration, and package-level composition. It contains no substantial command implementation.
+
+Each leaf command module owns one command handler and its command-specific argument/output mapping.
+Tests are colocated:
+
+```text
+src/cli/commands/projects/list.ts
+src/cli/commands/projects/list.test.ts
+```
+
+Do not add command-group barrels unless the group intentionally exposes an API or requires genuine
+composition.
+
+## Naming exception
+
+Command filenames follow public CLI segments rather than exported handler names:
+
+```text
+command:  ankh studio projects list
+file:     src/cli/commands/projects/list.ts
+handler:  listProjects
+```
+
+This is an intentional exception to primary-symbol filenames. It applies only to CLI command leaf
+modules.
+
+## Adapter boundary
+
+A handler may parse `request.argv`, use the provided command context, call package-owned
+application operations, translate failures into command results, and create the package
+composition needed for the invocation.
+
+A handler must not:
+
+- implement domain rules;
+- duplicate application behavior;
+- implement substantial filesystem, network, process, database, credential, or provider logic;
+- proxy behavior owned by another package to place it under the local prefix;
+- preserve removed commands through aliases or hidden handlers.
+
+## Capabilities and public metadata
+
+Keep provider metadata, command definitions, handler paths, public exports, documentation, and
+tests synchronized. Remove unused capabilities when a command disappears. Published command or
+metadata changes require the repository's normal changeset treatment.
+
+## Standalone generated applications
+
+Generated applications own their installation, validation, build, and runtime commands. Execute
+the generated application's canonical command with that application as `cwd`.
+
+Studio must not own a parallel workspace-install command or assume generated applications are
+Studio workspace members. Do not preserve obsolete workspace commands, capabilities, handlers,
+tests, or documentation after the standalone architecture replaces them.

package/dist/tools/skills/assets/ankhorage-project-structure/references/expo-apps.md

@@ -0,0 +1,43 @@
+# Expo and React Native Applications
+
+An Expo application is an independently installable application and may use ports-and-adapters
+principles for its application behavior. Expo Router route files are framework-owned inbound
+adapters, not the home of domain logic.
+
+## Structure
+
+```text
+app/                         # Expo Router route tree
+src/
+  app/                       # providers and app composition
+  <domain>/                  # application-owned domains
+    domain/
+    application/
+    ports/
+  platform/                  # app-local native/web adapters only
+  utils/                     # app-wide internal utilities
+```
+
+Keep route files thin: resolve route parameters and navigation context, invoke or render the owning
+application boundary, and declare route-specific framework configuration. Substantial UI belongs
+with its owning domain or reusable UI package.
+
+## Ankhorage ownership
+
+- Use Contracts for portable authored state.
+- Use Runtime for manifest/action/data execution.
+- Use ZORA and Surface for reusable UI.
+- Use Expo Runtime and provider packages for platform integration.
+- Do not copy package behavior into the generated app merely to avoid a public API or release.
+- Do not import Studio source or rely on the Studio workspace.
+
+## Standalone lifecycle
+
+Each generated app owns its package manifest, lockfile, installation, validation, build, and
+deployment inputs. A parent dashboard may invoke commands with the app as `cwd`, but must not
+install it through a hidden shared workspace contract.
+
+## Platform variants
+
+Use `.native`, `.web`, `.ios`, and `.android` variants only when the platform behavior genuinely
+differs. Keep the portable contract in the unsuffixed module and concrete behavior at the edge.

package/dist/tools/skills/assets/ankhorage-project-structure/references/hexagonal-architecture.md

@@ -0,0 +1,120 @@
+# Ankhorage Ports and Adapters
+
+Use ports-and-adapters principles for application, engine, service, and hybrid packages. The
+Ankhorage package is the hexagon; internal domains are not independent feature packages.
+
+## Purpose
+
+Protect stable package policy from React, Expo, HTTP, Fastify, Bun, filesystem, process, database,
+provider SDK, and test-harness details. The useful rule is dependency direction, not a mandatory
+folder ceremony.
+
+```text
+package edge / adapter -> application -> domain
+                              |
+                              v
+                         required ports
+
+concrete adapter -> required port
+```
+
+## Roles
+
+- **Domain:** pure rules, values, invariants, and deterministic transformations owned by the
+  package.
+- **Application:** command-independent use cases and orchestration of domain behavior.
+- **Port:** a capability contract required by application/domain code to reach an external edge.
+- **Inbound adapter:** converts CLI, HTTP, UI, Runtime, worker, or test input into an application
+  invocation.
+- **Outbound adapter:** implements a required port using filesystem, process, provider, storage,
+  network, Expo, or another package.
+- **Composition:** selects implementations and wires adapters to application operations.
+
+Ports belong beside the application/domain code that needs them. Do not create a global
+`src/ports/` dumping ground.
+
+## Package-level edges
+
+Ankhorage preserves recognizable package edges:
+
+```text
+src/app/       React or React Native composition and package-wide UI entrypoints
+src/cli/       one package-level Ankh provider
+src/host/      Bun/Node/Fastify/filesystem composition and shared host infrastructure
+src/platform/  native, web, Expo, or provider-specific implementations
+```
+
+Internal domain behavior must not migrate into these directories merely because an adapter calls
+it. Edges translate and compose; domains own behavior.
+
+## Domain-first organization
+
+Substantial domains may use role directories:
+
+```text
+src/
+  projects/
+    contracts/
+    domain/
+    application/
+    ports/
+  deploy/
+    contracts/
+    domain/
+    application/
+    ports/
+```
+
+Small domains remain flat while their siblings have the same role. Introduce role directories
+when definitions, parsers, use cases, adapters, or utilities begin mixing at one level.
+
+Do not use:
+
+```text
+src/features/
+src/common/
+src/core/
+src/shared/
+src/ports/
+```
+
+unless a repository has an explicit, narrower meaning that cannot be represented by an owning
+domain or package edge.
+
+## When a port is justified
+
+Create a port when at least one is true:
+
+- more than one real adapter exists or is planned by current architecture;
+- deterministic tests need to replace a side effect;
+- the dependency is volatile or provider-specific;
+- the same application operation is invoked through multiple inbound edges;
+- the capability crosses a package, process, storage, network, platform, or credential boundary.
+
+Do not create a port merely because a function calls another function. Pure utilities, component
+composition, value transformations, and React-local presentation state usually do not need ports.
+
+## React and React Native
+
+React/RN UI is an inbound edge. Components may collect input, render state, and invoke application
+actions. Provider execution and durable business rules remain outside components and hooks.
+
+- Keep navigation route modules thin.
+- Keep UI-specific transient state near the UI.
+- Move reusable business decisions and cross-interface operations into the owning domain or
+  application layer.
+- Inject values, callbacks, or capability interfaces into reusable UI rather than importing
+  concrete providers.
+
+## Composition roots
+
+Keep wiring explicit and limited to package entrypoints such as app startup, host creation, CLI
+provider construction, or a focused factory. Do not use ambient service locators or hidden mutable
+registries as dependency injection.
+
+## Testing
+
+- Test domain and application behavior with deterministic inputs and fake ports.
+- Test concrete adapters against their real protocol boundary.
+- Test user-facing flows through inbound edges only where the integration adds evidence.
+- Do not duplicate the full acceptance matrix for every internal refactor.

package/dist/tools/skills/assets/ankhorage-project-structure/references/migration.md

@@ -0,0 +1,61 @@
+# Structural Migration
+
+Use this reference when the user requests repository cleanup, file movement, boundary correction,
+or adoption of the project structure.
+
+## Establish the target first
+
+Before moving code:
+
+1. inventory direct `src/` files, current domains, entrypoints, tests, and generated sources;
+2. inventory package exports and consumers of public subpaths;
+3. classify the repository profile;
+4. identify code that belongs in another package;
+5. define the intended final directory tree and dependency direction;
+6. identify Utility additions and release gates;
+7. identify obsolete behavior that should be deleted rather than relocated.
+
+Do not begin with a mechanical folder move while ownership remains unresolved.
+
+## Migration units
+
+Migrate cohesive domains or vertical capabilities, not arbitrary batches of similarly named files.
+For each unit:
+
+1. extract any required cross-repository utility first;
+2. release the owning package before updating consumers;
+3. move domain/application code and tests together;
+4. move concrete edge behavior to its package-level adapter area;
+5. preserve intentional public package subpaths by remapping exports to nested output;
+6. remove obsolete barrels, aliases, and duplicate paths;
+7. validate the focused unit before the full repository gates.
+
+Avoid a single repository-wide move when smaller coherent migrations give clearer review and
+rollback boundaries. Avoid tiny PRs that leave two competing architectures active for long periods.
+
+## Root source policy
+
+At the target state, direct `src/` files are limited to intentional entrypoints such as `index.ts`,
+`root.ts`, required environment declarations, or other explicitly documented build entrypoints.
+Public export status alone does not justify root placement.
+
+## Acceptance and enforcement
+
+After the structure is proven in a representative repository:
+
+- distribute the canonical structure skills through `ankh devtools sync` into
+  `.agents/skills/<skill-name>/` as described in
+  [skill-distribution.md](skill-distribution.md);
+- add Devtools import-boundary rules where static enforcement is reliable;
+- add Doctor profile checks for allowed root files and required package entrypoints;
+- use Knip to verify public exports and dead compatibility barrels;
+- keep repository `AGENTS.md` focused on repository-specific ownership rather than duplicating this
+  skill.
+
+Enforcement belongs to Devtools and Doctor, not prose-only repository exceptions.
+
+## No behavior drift
+
+A structural migration preserves current valid behavior unless deletion is an explicit part of the
+approved target architecture. Do not add compatibility implementations solely because files move.
+Use characterization or focused public-surface tests when a move crosses a meaningful boundary.

package/dist/tools/skills/assets/ankhorage-project-structure/references/repository-profiles.md

@@ -0,0 +1,91 @@
+# Repository Profiles
+
+Select one primary profile from the repository's actual ownership and consumers. A package may
+also expose secondary edges such as CLI or Expo without changing its primary profile.
+
+## Application, engine, or hybrid
+
+Use for packages that coordinate use cases, state transitions, external systems, or several
+delivery mechanisms.
+
+Typical structure:
+
+```text
+src/
+  index.ts
+  <domain>/
+    contracts/
+    domain/
+    application/
+    ports/
+  app/                 # optional React/RN edge and composition
+  cli/                 # optional package-level Ankh edge
+  host/                # optional Bun/Node/HTTP/filesystem edge
+  platform/            # optional native/web/provider edge
+  utils/               # internal cross-domain utilities only
+```
+
+Create role subdirectories only when a domain has enough distinct responsibilities to need them.
+Do not pre-create empty `contracts`, `domain`, `application`, or `ports` directories.
+
+## Contracts or value library
+
+Contracts own portable shape and structural validation, not provider execution.
+
+```text
+src/
+  index.ts
+  <domain>/
+    contracts/
+    parsers/
+    constants/
+    tests colocated with their owner
+```
+
+- Keep modules deterministic and side-effect free.
+- Type definitions and structural parsers change together.
+- Provider readiness, network state, filesystem state, and UI behavior stay in their owner.
+- Avoid `Record<string, unknown>` escape hatches when a canonical concept can be modeled.
+
+## Platform or provider adapter
+
+These packages deliberately implement an external technology boundary.
+
+```text
+src/
+  index.ts
+  contracts/           # provider-facing public configuration when owned here
+  planning/            # pure capability/configuration planning
+  adapters/            # concrete provider/platform implementations
+  composition/         # factories or provider registration
+  cli/                 # only when this package exposes Ankh commands
+```
+
+- Depend on portable contracts or ports from lower-level owning packages.
+- Do not redefine the application/domain model locally.
+- Keep provider SDK values from leaking through portable public contracts.
+- Separate build-time planning from runtime execution when both exist.
+
+## Tooling package
+
+Tooling packages may be command-centric but still keep parsing, policy, and side effects distinct.
+
+```text
+src/
+  cli/
+  policy/              # deterministic rules and diagnostics
+  application/         # command-independent operations
+  adapters/            # filesystem, process, GitHub, registry, etc.
+  composition/
+  index.ts
+```
+
+The package remains the boundary. Do not create internal pseudo-packages beneath `features/`.
+
+## Generated or standalone application
+
+A generated application is an independently installable and buildable project. It is not a
+workspace child of Studio and must not depend on Studio-local source or installation state.
+
+Use the Expo application profile when applicable. Application-specific domains live under `src/`;
+route entrypoints remain thin.

package/dist/tools/skills/assets/ankhorage-project-structure/references/skill-distribution.md

@@ -0,0 +1,115 @@
+# Repository Skill Distribution
+
+Use this reference when adding Ankhorage-owned skills to repositories or changing Devtools
+synchronization.
+
+## Canonical destination
+
+Repository-local skills live at:
+
+```text
+.agents/
+  skills/
+    <skill-name>/
+      SKILL.md
+      agents/             # optional
+      references/         # optional
+      scripts/            # optional
+      assets/             # optional
+```
+
+The directory name must equal the skill's frontmatter `name`. Synchronize the complete skill
+directory, not only `SKILL.md`. Do not use `.agent/`, `.codex/skills/`, or a package source
+directory as the shared repository location.
+
+## Devtools ownership
+
+`@ankhorage/devtools` is the distribution authority for canonical Ankhorage-owned repository
+skills. It packages immutable skill sources with the released Devtools version; synchronization
+must not fetch mutable files from GitHub at runtime.
+
+The aggregate commands include the skills scope:
+
+```text
+ankh devtools sync [target]
+ankh devtools status [target]
+```
+
+Also expose focused commands for diagnosis and intentional updates:
+
+```text
+ankh devtools skills sync [target]
+ankh devtools skills status [target]
+```
+
+Their provider capabilities are `devtools.skills.sync` and `devtools.skills.status`.
+
+## Skill selection
+
+Do not copy every available skill into every repository.
+
+- Devtools defines a small baseline of organization-wide Ankhorage skills.
+- Profile-specific Ankhorage skills are selected from repository traits or explicit package
+  metadata when automatic detection would be ambiguous.
+- External, personal, experimental, and task-specific skills are not part of Devtools sync.
+- A repository may own additional skill directories beside the Devtools-managed set.
+
+Prefer the same repository-trait detection used by other Devtools profiles. Add explicit metadata
+only for an actual ambiguity; do not require each repository to repeat a default skill list.
+
+## Managed-tree semantics
+
+Treat each selected canonical skill as an exactly managed directory while preserving the rest of
+`.agents/skills/`.
+
+- Create or replace every canonical file in a selected managed skill.
+- Remove stale files and obsolete skills only when prior Devtools ownership is recorded.
+- Never delete an unowned skill directory or an untracked file merely because it is absent from
+  the Devtools bundle.
+- Record the managed skill names, relative file paths, source Devtools version, and content hashes
+  in a Devtools ownership manifest.
+- Make `sync` idempotent. Make `status` and `--dry-run` report created, updated, removed, and
+  unchanged paths without mutation.
+
+The ordinary single-file managed-file abstraction is insufficient if it cannot report or remove
+stale owned files. Use a managed-tree abstraction or extend the ownership manifest rather than
+deleting `.agents/skills/` wholesale.
+
+## Suggested Devtools source layout
+
+Keep the package-level CLI edge separate from synchronization policy and packaged skill assets:
+
+```text
+src/
+  cli/
+    commands.ts
+    runRepositoryCommand.ts
+  tools/
+    skills/
+      index.ts
+      managed.ts
+      selection.ts
+      assets/
+        <skill-name>/
+          SKILL.md
+          ...
+```
+
+The exact filenames may follow the existing Devtools conventions. The important boundaries are:
+
+- `src/cli/` declares and dispatches `skills sync` and `skills status`;
+- skill selection and managed-tree policy stay outside the CLI;
+- packaged skill directories are release artifacts, not runtime network dependencies.
+
+## Validation
+
+Doctor should validate that:
+
+- every selected managed skill exists at `.agents/skills/<skill-name>/`;
+- directory and frontmatter names agree;
+- managed files match the released Devtools bundle;
+- the ownership manifest contains no unsafe paths;
+- repository-owned skills remain permitted and are not falsely reported as drift.
+
+Devtools remains responsible for applying and reporting synchronization. Doctor reports contract
+violations; it does not rewrite skill trees.

package/dist/tools/skills/assets/ankhorage-project-structure/references/studio.md

@@ -0,0 +1,134 @@
+# Studio Structure Example
+
+Read this only for `ankhorage/studio`. It is a structural target and ownership checklist, not a
+license to move every file in one change.
+
+Studio is an application/hybrid package. The Studio package is the bounded capability; its internal
+responsibilities are domains, not independently bound `features`.
+
+## Target source tree
+
+```text
+src/
+  index.ts
+  root.ts
+
+  app/                         # React/RN application edge and composition
+  cli/                         # one Studio Ankh provider
+  host/                        # Bun/Fastify/filesystem edges and host composition
+  platform/                    # Studio-local native/web implementations only
+
+  auth/
+  bindings/
+  canvas/
+  deploy/
+  diagnostics/
+  external-apis/
+  manifest/
+  media/
+  modules/
+  projects/
+  properties/
+  routes/
+  secrets/
+  selection/
+  templates/
+  workspace/
+
+  utils/
+
+test/
+  acceptance/
+  e2e/
+  fixtures/
+  smoke/
+```
+
+Substantial domains may contain `contracts`, `domain`, `application`, `ports`, and domain-local
+`utils` when those roles genuinely exist. Do not pre-create all role directories.
+
+## Studio CLI
+
+The command tree mirrors paths after the `studio` prefix:
+
+```text
+src/cli/
+  index.ts
+  commands/
+    dev.ts
+    projects/
+      create.ts
+      delete.ts
+      list.ts
+      sync.ts
+```
+
+Mappings:
+
+```text
+ankh studio dev              -> commands/dev.ts
+ankh studio projects create  -> commands/projects/create.ts
+ankh studio projects delete  -> commands/projects/delete.ts
+ankh studio projects list    -> commands/projects/list.ts
+ankh studio projects sync    -> commands/projects/sync.ts
+```
+
+`ankh studio workspace install` is not part of the target. Generated apps are standalone and own
+their installation. Remove the obsolete command, handler, capability, tests, and documentation
+rather than relocating them.
+
+## Current directory disposition
+
+- Root `binding*` modules move into `bindings/`.
+- Root `canvas*` and insert/placement behavior move into `canvas/`.
+- Root `projectDeploy*`, host deploy code, deploy routes, and deploy UI converge under the `deploy`
+  domain and package-level edges.
+- Root auth settings/health/OAuth behavior and host auth implementations converge under `auth` and
+  package-level edges.
+- Root external API contracts/model code, host API services, routes, and UI converge under
+  `external-apis` and package-level edges.
+- Root media authoring code, host media implementations, and media UI converge under `media` and
+  package-level edges.
+- Root module admin code and host module integration converge under `modules` and package-level
+  edges.
+- Root project/workspace models, current app project screens, hooks, project store/generation
+  operations, and matching adapters converge under `projects`, `templates`, or `workspace` according
+  to actual ownership.
+- Root secret API/usage/response behavior, host secret implementations, routes, and UI converge
+  under `secrets` and package-level edges.
+- Route and admin-route behavior moves under `routes`.
+- Selection, measurement, stationary selection, and canvas interaction behavior must be separated
+  between `selection` and `canvas` by actual invariant ownership.
+- The current generic `core/` directory disappears; each file moves to its owning domain or package
+  edge.
+- The current generic `runtime/` directory is reviewed symbol by symbol. Shared runtime behavior
+  moves to `@ankhorage/runtime`; Studio-specific application integration moves to `app/` or its
+  owning domain.
+- Feature-specific UI moves beside its owning domain. Only package-wide UI composition remains in
+  `app/`.
+- Host smoke and acceptance infrastructure moves outside production source to `test/`.
+
+## Utility gates
+
+The existing own-property helpers explicitly marked for Utility extraction should move through
+`@ankhorage/utility` before Studio consumes them. Repeated generic unknown-value narrowing should
+be evaluated under `@ankhorage/utility/object` or `@ankhorage/utility/value`; semantic payload
+parsers remain domain-owned.
+
+## Suggested migration order
+
+Use lower-entanglement domains to prove the structure before moving the largest state models:
+
+1. external APIs;
+2. modules;
+3. media;
+4. secrets;
+5. projects and templates;
+6. deploy;
+7. auth;
+8. canvas and selection;
+9. routes;
+10. manifest.
+
+Reassess cross-package ownership during every unit. Moving a misplaced behavior deeper into Studio
+is not a successful migration when another Ankhorage package owns it.