@ankhorage/devtools 1.19.18 → 1.20.0

package/README.md

@@ -3,7 +3,7 @@
 
 # @ankhorage/devtools
 
-![license: MIT](././paradox/badges/license.svg) ![npm: v1.19.18](././paradox/badges/npm.svg) ![runtime: bun](././paradox/badges/runtime.svg) ![typescript: strict](././paradox/badges/typescript.svg) ![eslint: checked](././paradox/badges/eslint.svg) ![prettier: checked](././paradox/badges/prettier.svg) ![build: checked](././paradox/badges/build.svg) ![tests: checked](././paradox/badges/tests.svg) ![docs: paradox](././paradox/badges/docs.svg)
+![license: MIT](././paradox/badges/license.svg) ![npm: v1.20.0](././paradox/badges/npm.svg) ![runtime: bun](././paradox/badges/runtime.svg) ![typescript: strict](././paradox/badges/typescript.svg) ![eslint: checked](././paradox/badges/eslint.svg) ![prettier: checked](././paradox/badges/prettier.svg) ![build: checked](././paradox/badges/build.svg) ![tests: checked](././paradox/badges/tests.svg) ![docs: paradox](././paradox/badges/docs.svg)
 
 Shared tooling, repository automation, runtime policies, and agent standards for Ankhorage TypeScript projects
 

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

@@ -36,71 +36,57 @@ repository root. Do not resolve it relative to this skill's own installation loc
 
 1. `<repo-root>/.agents/skills/hexagonal-architecture/SKILL.md`
 
-## Required source layout
-
-- `examples/`: Repository-root folder in this standalone repository;
-  Use it for complete, intentional, user-facing examples that people can inspect, copy, install, and run independently of a monorepo or internal fixture layout.
-
-Each example lives in a named subdirectory, such as `examples/basic-usage/*.ts`. Do not put example
-source files directly under `examples/`.
-
-Test-only fixtures remain owned by the applicable test structure. Do not relabel fixtures as public
-examples merely to bypass repository structure rules.
-
-- `src/cli/` must exist or have a concrete issue tracking the missing CLI commands;
-  CLI modules are thin inbound adapters: they parse input, invoke a feature use case, and render
-  output.
-
-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
-```
-
-The package prefix is represented by the provider and is not repeated under `commands/`. Flags and
-positional arguments do not affect this directory tree. Each command file follows the one-export
-rule: `commands/projects/list.ts` exports `list` and owns only the command-specific input/output
-mapping.
-
-- `src/features/`: Lists the repository's actual product capabilities;
-  Technical categories are not features. Each feature owns its own hexagonal structure as needed,
-  following the required Hexagonal Architecture skill. Do not create empty layers.
-
-```text
-examples/
-  <example>/
-src/
-  cli/
-    createCliProvider.ts
-    commands/
-      <command>.ts
-      <group>/
-        <command>.ts
-  features/
-    <feature>/
-      domain/
-      application/
-        ports/
-          inbound/
-          outbound/
-        use-cases/
-      adapters/
-        inbound/
-        outbound/
-      composition/
-      constants/
-        <topic>.ts
-      utils/
-  types/
-    <topic>.ts
-  constants/
-    <topic>.ts
-  utils/
-```
-
-Keep only deliberate package facades directly under `src/`. Public package subpaths must name their
-explicit module in `package.json`; generic `index.ts` barrels are not public API exceptions.
+## Architecture profiles and source layout
+
+Do not impose one folder tree on every repository. Select the smallest profile that matches the
+repository's real responsibility, then enforce that profile's vocabulary and dependency direction.
+Read `references/architecture-profiles.md` and `references/hexagonal-invariants.md` before
+creating or moving architectural directories.
+
+Valid profiles include:
+
+- simple/value/contracts library;
+- reusable UI or design-system library;
+- application, engine, or hybrid package;
+- provider or platform adapter package;
+- tooling package;
+- generated standalone application;
+- an explicitly documented repository-specific profile such as Studio.
+
+A package may start flat. Introduce `domain/`, `application/`, `ports/`, `adapters/`,
+`composition/`, `features/`, or `core/` only when those names communicate a real architectural
+role. Once a vocabulary is introduced, its combinations must be coherent:
+
+- `domain/` may stand alone and must remain independent from outer mechanisms;
+- `application/` coordinates use cases and may depend inward on domain policy and required ports;
+- `ports/` define capabilities required by inner policy; they do not implement provider technology;
+- `adapters/` translate or implement a port at an external edge and therefore require an inward
+  capability boundary to adapt to;
+- `composition/` is outer wiring and exists only when concrete implementations need selection;
+- `features/` is feature-first organization, not a generic bucket. Each feature owns a coherent
+  slice and may introduce only the role directories it actually needs;
+- `core/` is allowed only when the repository defines it narrowly as stable inner policy. It must
+  never become a miscellaneous dumping ground.
+
+Dependency direction is the invariant. Inner policy must not import outer mechanisms. A domain or
+core module must not depend on application orchestration, adapters, composition, CLI, host,
+platform, framework, database, or provider implementation details. Application/use-case code must
+not import concrete adapters or composition roots. Adapters may depend inward on ports/application/
+domain contracts. Composition may depend on all pieces it wires.
+
+Do not create empty layers for symmetry. A small package with no domain orchestration does not need
+hexagonal ceremony. UI libraries use component/foundation dependency direction rather than fake
+application ports. Contracts libraries remain portable and side-effect free.
+
+Repository-root `examples/` contains complete user-facing examples. Each example lives in a named
+subdirectory. Test-only fixtures remain test-owned.
+
+Package-level delivery edges such as `src/cli/`, `src/host/`, `src/app/`, or `src/platform/`
+remain thin adapters/composition boundaries. The filesystem below `src/cli/commands/` mirrors the
+public Ankh command path, and command modules parse input, invoke package behavior, and render output.
+
+Keep only deliberate public facades directly under `src/`. Public package subpaths must map to
+explicit package exports; generic barrels are not an excuse to bypass ownership.
 
 ## General Taxonomy
 

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

@@ -0,0 +1,141 @@
+# Architecture Profiles
+
+Choose the profile from actual ownership and consumers. Profiles define allowed vocabulary and
+dependency direction; they are not templates that require every listed directory.
+
+## Simple, value, or contracts library
+
+Use for portable types, deterministic values, parsers, constants, algorithms, and small libraries
+without application orchestration.
+
+Typical forms:
+
+```text
+src/
+  index.ts
+  <domain-or-topic>/
+  types/
+  constants/
+  utils/
+```
+
+Do not invent ports, adapters, application, or composition layers when there is no external edge to
+abstract. Contracts packages additionally keep public declarations serializable and free of runtime
+implementation.
+
+## Reusable UI or design-system library
+
+Use semantic UI ownership and stable foundation layers rather than fake use cases:
+
+```text
+src/
+  foundation/
+  theme/
+  layout/
+  primitives/
+  components/
+  patterns/
+  registry/
+```
+
+Higher-level UI may depend on lower-level foundations; foundations must not depend upward on composed
+components or registries. Provider execution belongs outside reusable presentation components.
+
+## Application, engine, or hybrid package
+
+Use when the package owns use cases, state transitions, external systems, or several delivery edges.
+Domain-first and feature-first organization are both valid when coherent.
+
+Domain-first example:
+
+```text
+src/
+  <domain>/
+    domain/
+    application/
+    ports/
+    adapters/
+    composition/
+  cli/
+  host/
+  app/
+  platform/
+```
+
+Feature-first example:
+
+```text
+src/
+  features/
+    <feature>/
+      domain/
+      application/
+      ports/
+      adapters/
+      composition/
+  cli/
+```
+
+Only create the role directories that the capability actually needs. A pure domain feature can stop
+at `domain/`; an in-memory use case need not invent an outbound adapter.
+
+## Provider or platform adapter package
+
+Use when the package deliberately implements an external technology boundary:
+
+```text
+src/
+  contracts/
+  planning/
+  adapters/
+  composition/
+  cli/
+```
+
+Portable configuration and planning stay independent from SDK/runtime values. Concrete provider code
+stays in adapters.
+
+## Tooling package
+
+Command-centric tooling may use:
+
+```text
+src/
+  cli/
+  policy/
+  application/
+  adapters/
+  composition/
+```
+
+Policy remains deterministic. Filesystem, process, registry, network, and GitHub behavior stay at
+the edge.
+
+## Generated standalone application
+
+A generated app owns its manifest, lockfile, installation, validation, build, and deployment inputs.
+A parent tool may invoke it with the app as `cwd`, but it must not depend on a hidden parent
+workspace, sibling source, or installation state.
+
+## Repository-specific profile
+
+A repository may define a narrower profile when its domain genuinely needs one. That profile must be
+documented in the managed project-structure skill or an explicit repository reference and must still
+respect the shared standalone and dependency-direction invariants. Studio is the canonical example:
+its `features/` taxonomy is intentional and each substantial feature may layer internally.
+
+## Combination rules
+
+Folder names create obligations:
+
+- `domain/`: inner policy; no outward mechanism dependencies.
+- `application/`: use-case orchestration; no concrete adapter/composition dependency.
+- `ports/`: capability contracts required by inner policy.
+- `adapters/`: concrete edge implementations; there must be an inward capability/policy to adapt.
+- `composition/`: selects and wires concrete implementations; do not create it without pieces to wire.
+- `features/`: siblings are product capabilities, not technical categories.
+- `core/`: only a narrowly defined inner-policy layer; never a generic dumping ground.
+- `common/`, `shared/`, and `helpers/`: not architectural ownership categories.
+
+Doctor should validate these combinations and dependency directions rather than require every
+repository to match one tree.

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

@@ -0,0 +1,80 @@
+# Hexagonal Architecture Invariants
+
+The canonical rule is isolation of inner policy from external mechanisms, not the visual shape or a
+fixed number of directories.
+
+## Research basis
+
+- Alistair Cockburn's original Ports & Adapters article defines an application on the inside
+  communicating through purposeful ports with replaceable technology-specific adapters. It
+  explicitly notes that the number of ports is not fixed:
+  https://alistair.cockburn.us/hexagonal-architecture
+- Robert C. Martin's Clean Architecture states the Dependency Rule: source dependencies point
+  inward, while outer mechanisms must not leak names or formats into inner policy:
+  https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html
+- Martin Fowler describes layering as a logical separation that can exist at different granularities
+  and notes that larger systems often modularize primarily by domain, layering inside those modules:
+  https://martinfowler.com/bliki/PresentationDomainDataLayering.html
+- DDD-oriented layered architecture keeps domain rules independent from infrastructure while the
+  application layer coordinates use cases and infrastructure implements technical details:
+  https://learn.microsoft.com/dotnet/architecture/microservices/microservice-ddd-cqrs-patterns/ddd-oriented-microservice
+
+## Invariants
+
+```text
+outer adapter/composition -> application/use case -> domain/core policy
+                                  |
+                                  v
+                           required port contract
+
+concrete adapter ----------------> required port contract
+```
+
+The exact filesystem can vary, but source dependencies must preserve this direction.
+
+### Inner policy
+
+Domain/core policy owns deterministic rules, values, invariants, and transformations. It must not
+import:
+
+- CLI, HTTP, UI, worker, or framework entrypoints;
+- filesystem/process/network/database/provider SDK implementations;
+- adapters or composition roots;
+- application orchestration that sits outside that policy.
+
+### Application/use cases
+
+Application code coordinates domain policy and required capabilities. It may define or consume port
+contracts, but it must not import concrete adapter implementations or composition roots.
+
+### Ports
+
+A port names a capability or conversation at a boundary. Create one when an external side effect,
+provider, process, platform, storage mechanism, or multiple delivery mechanisms justify substitution
+or deterministic testing. A port is not required for an ordinary pure function call.
+
+### Adapters
+
+Adapters translate at the edge. Inbound adapters map CLI/HTTP/UI/worker input into an application
+operation. Outbound adapters implement required capabilities using concrete technology.
+
+An `adapters/` directory without any identifiable inward policy/capability boundary is structurally
+suspicious: technology has become the architecture instead of adapting it.
+
+### Composition
+
+Composition selects implementations and wires dependencies. It is intentionally outermost and may
+know concrete adapters. Inner policy must never import it.
+
+## Verification strategy
+
+Doctor should validate what can be proven statically:
+
+- local dependency protocols and sibling-source coupling;
+- folder-role combinations after a vocabulary is introduced;
+- relative import direction between recognized roles;
+- generic catch-all architecture directories;
+- public-package standalone scripts and packed artifact boundaries.
+
+Semantic independence that cannot be inferred statically belongs in the package-owned
+`test:standalone` suite. Release must execute both Doctor and that owner test.

package/dist/tools/skills/assets/hexagonal-architecture/SKILL.md

@@ -35,6 +35,15 @@ Dependency direction is always inward:
 - Domain -> domain-only abstractions (no framework or infrastructure dependencies)
 - Domain -> nothing external
 
+## Structural rule
+
+Hexagonal architecture does not prescribe one mandatory directory tree or a fixed number of ports.
+The enforceable contract is dependency direction and replaceability: inner policy must remain
+independent from outer technology, and adapters translate external mechanisms at explicit
+boundaries. Use the repository's managed `ankhorage-project-structure` skill to select a concrete
+profile and validate folder-role combinations. Do not create empty layers or ports merely to match
+a diagram.
+
 ## How It Works
 
 ### Step 1: Model a use case boundary

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/devtools",
-  "version": "1.19.18",
+  "version": "1.20.0",
   "description": "Shared tooling, repository automation, runtime policies, and agent standards for Ankhorage TypeScript projects",
   "license": "MIT",
   "homepage": "https://github.com/ankhorage/devtools#readme",
@@ -150,7 +150,7 @@
   "devDependencies": {
     "@ankhorage/paradox": "^0.1.26",
     "@ankhorage/ankh": "^0.10.4",
-    "@ankhorage/doctor": "0.10.39",
+    "@ankhorage/doctor": "0.10.40",
     "@techstark/opencv-js": "^5.0.0-release.1",
     "@types/bun": "^1.4.1",
     "@types/node": "^26.6.2",