hammerkit 1.6.0 → 1.8.0

package/specs/build-file/environment-variables/spec.md

@@ -1,82 +0,0 @@
-# Feature Specification: Build File: Environment Variables
-
-**Feature Branch**: `001-current-state-specs`
-
-**Created**: 2026-05-30
-
-**Status**: Current State (reverse-specified from docs, hammerkit 1.6.0)
-
-**Input**: Existing behavior documented in `docs/build-file/environment-variables.md`
-
-## User Scenarios & Testing *(mandatory)*
-
-### User Story 1 - Pass shell environment variables into a task (Priority: P1)
-
-A developer needs a task to use a variable (e.g. `VERSION`) that is set in the shell before running hammerkit. They declare the variable in the task's `envs:` block referencing the shell value (`$VERSION`). Hammerkit validates the variable is set and injects it into the task execution environment.
-
-**Why this priority**: This is the most common env-var pattern; it prevents silent failures from unset variables.
-
-**Independent Test**: Export a variable in the shell, declare it in the task `envs:`, run the task, and confirm the command receives the correct value. Then unset the variable and confirm hammerkit throws an error rather than passing an empty value.
-
-**Acceptance Scenarios**:
-
-1. **Given** a shell variable `VERSION=1.0.0` is exported, **When** a task declares `VERSION: $VERSION` in its `envs:` and runs `echo $VERSION`, **Then** the output is `1.0.0`.
-2. **Given** a task declares `VERSION: $VERSION` but the shell variable is not set, **When** the task is invoked, **Then** hammerkit throws an error before executing any commands.
-
-### User Story 2 - Use .env file for secret values (Priority: P2)
-
-A developer stores sensitive credentials (e.g. `NPM_TOKEN`) in a `.env` file that is excluded from version control. The task `envs:` block references the variable using the `$NPM_TOKEN` syntax. Hammerkit reads the `.env` file and makes the value available to the task.
-
-**Why this priority**: Keeps secrets out of the build file and version history while still being available during task execution.
-
-**Independent Test**: Create a `.env` file with `NPM_TOKEN=abc`, declare it in the task `envs:`, run the task, and confirm the token is available to the command.
-
-**Acceptance Scenarios**:
-
-1. **Given** a `.env` file containing `NPM_TOKEN=abc`, **When** a task declares `NPM_TOKEN: $NPM_TOKEN` in its `envs:` and is executed, **Then** the command receives `NPM_TOKEN=abc`.
-
-### User Story 3 - Define environment variables in the build file (Priority: P2)
-
-A developer defines default values for environment variables at the top-level `envs:` block or within a specific task's `envs:` block. Task-level declarations override the file-level defaults for that task only.
-
-**Why this priority**: Centralises configuration that does not change per-developer while allowing per-task overrides.
-
-**Independent Test**: Declare `NODE_VERSION: 14.16.0` at the top level and `NODE_VERSION: 14.0.0` inside one task's `envs:`. Run each task and verify each receives the correct version string.
-
-**Acceptance Scenarios**:
-
-1. **Given** `NODE_VERSION: 14.16.0` is declared in the top-level `envs:`, **When** a task that does not override it runs `echo $NODE_VERSION`, **Then** the output is `14.16.0`.
-2. **Given** a task declares `NODE_VERSION: 14.0.0` in its own `envs:`, **When** that task runs, **Then** its value (`14.0.0`) takes precedence over the top-level value.
-3. **Given** top-level `envs:` are declared in file A, **When** a task from a referenced or included build file B runs, **Then** it does NOT have access to file A's top-level env vars.
-
-### Edge Cases
-
-- Referencing an undefined shell variable that is not in `.env` causes a hard error before task execution begins.
-- Variables declared in a build file's top-level `envs:` are scoped to that file; they do not leak into referenced or included build files.
-- The `.env` file is loaded relative to the project directory containing the build file.
-
-## Requirements *(mandatory)*
-
-### Functional Requirements
-
-- **FR-001**: The system MUST support declaring environment variables in the top-level `envs:` map of a build file, making them available to all tasks in that file.
-- **FR-002**: The system MUST support declaring environment variables in a task-level `envs:` map, overriding any same-named top-level declaration for that task.
-- **FR-003**: The system MUST resolve `$VAR` references in `envs:` values from the shell environment at the time the task is executed.
-- **FR-004**: The system MUST read environment variable values from a `.env` file in the project directory and make them available for `$VAR` resolution.
-- **FR-005**: The system MUST throw an error if an `envs:` entry references a shell or `.env` variable that is not defined, rather than passing an empty or undefined value to the task.
-- **FR-006**: Top-level `envs:` declarations MUST be scoped to the build file in which they are defined and MUST NOT be visible to referenced or included build files.
-
-## Success Criteria *(mandatory)*
-
-### Measurable Outcomes
-
-- **SC-001**: A task that declares a shell-sourced env var receives the correct value when the variable is set, and hammerkit exits with a non-zero code and an error message when the variable is unset.
-- **SC-002**: A task that sources a value from `.env` receives the correct value without the secret appearing in the build file.
-- **SC-003**: A task-level `envs:` declaration overrides a file-level declaration for the same variable name within that task only.
-- **SC-004**: Tasks in a referenced or included build file do not inherit top-level env vars from the including build file.
-
-## Assumptions
-
-- `.env` file loading is automatic; no explicit declaration in the build file is needed beyond the `$VAR` reference in `envs:`.
-- Variables defined as literal values in `envs:` (not using `$VAR` syntax) are always available and require no shell validation.
-- The precedence order (most specific wins) is: task-level `envs:` > top-level `envs:` > `.env` file > shell environment, though the docs do not enumerate this explicitly; this assumption is recorded here for review.

package/specs/build-file/includes/spec.md

@@ -1,60 +0,0 @@
-# Feature Specification: Build File: Includes
-
-**Feature Branch**: `001-current-state-specs`
-
-**Created**: 2026-05-30
-
-**Status**: Current State (reverse-specified from docs, hammerkit 1.6.0)
-
-**Input**: Existing behavior documented in `docs/build-file/includes.md`
-
-## User Scenarios & Testing *(mandatory)*
-
-### User Story 1 - Reuse a shared task definition across multiple projects (Priority: P1)
-
-In a monorepo with multiple packages that each have a `package.json`, a developer extracts the common `npm install` task into a shared `build.npm.yaml` file at the repo root. Each package's build file declares an `includes:` entry pointing to that shared file under the alias `npm`. The `npm:install` task is then available as a dependency in each package and executes with the working directory set to the package that included it — not the location of the shared file.
-
-**Why this priority**: Includes are the canonical way to eliminate duplicated task definitions in monorepos; getting the working directory right is the core value proposition.
-
-**Independent Test**: Create a shared build file with a task that writes a file. Include it in two different package build files. Run `hammerkit npm:install` from each package context and confirm the output file is written to the respective package directory, not the shared file's directory.
-
-**Acceptance Scenarios**:
-
-1. **Given** `build.npm.yaml` at the repo root defines task `install`, and `packages/a/.hammerkit.yaml` declares `includes: { npm: ../../build.npm.yaml }`, **When** the user runs `npm:install` in the context of package `a`, **Then** the task executes with the working directory set to `packages/a/`.
-2. **Given** the same shared file is included in `packages/b/.hammerkit.yaml`, **When** `npm:install` runs in package `b`'s context, **Then** the working directory is `packages/b/`, independent of package `a`.
-3. **Given** `packages/b/.hammerkit.yaml` declares `deps: [npm:install, a:build]`, **When** the build task runs, **Then** `npm:install` runs in `packages/b/`'s working directory and `a:build` runs as a reference with `packages/a/`'s working directory.
-
-### Edge Cases
-
-- Includes differ from references in that the working directory is the location of the including build file, not the location of the included file.
-- Top-level `envs:` from the including build file are not visible to tasks in the included build file.
-- An included file can itself declare further references, mixing the two mechanisms as shown in the monorepo example.
-
-## Requirements *(mandatory)*
-
-### Functional Requirements
-
-- **FR-001**: The build file MUST support a top-level `includes:` map where each key is an alias and each value is a path to a shared build YAML file.
-- **FR-002**: Tasks from an included build file MUST be addressable using the `<alias>:<task-name>` notation from the CLI and in task `deps:` lists.
-- **FR-003**: When a task from an included build file executes, the working directory MUST be the directory of the build file that declared the `includes:` entry, NOT the directory of the included file.
-- **FR-004**: The same shared build file MAY be included by multiple build files, with each inclusion using the working directory of the including file independently.
-- **FR-005**: Includes and references MAY be combined in the same build file, allowing tasks from included files to coexist with tasks from referenced sub-projects as dependencies.
-
-### Key Entities
-
-- **Include**: A named entry in the `includes:` map; the key is the alias used to prefix task names, the value is the relative path to the shared build YAML file.
-
-## Success Criteria *(mandatory)*
-
-### Measurable Outcomes
-
-- **SC-001**: A task sourced from an included build file runs with the working directory of the including project, not the directory where the shared file resides.
-- **SC-002**: The same shared task file included by two different packages produces independent executions, each in their own package directory.
-- **SC-003**: A build file that combines `includes:` and `references:` correctly resolves both sets of task namespaces and executes each with the correct working directory.
-
-## Assumptions
-
-- Include paths are relative to the directory of the build file containing the `includes:` block.
-- Included files are standard hammerkit build YAML files and may contain any valid build file content (`tasks:`, `envs:`, etc.).
-- The working-directory rule applies to all task types within an included file (container tasks and local tasks alike), though the docs only illustrate local tasks.
-- Unlike references, includes do not require the target path to be a directory — they point directly to a `.yaml` file.

package/specs/build-file/references/spec.md

@@ -1,56 +0,0 @@
-# Feature Specification: Build File: References
-
-**Feature Branch**: `001-current-state-specs`
-
-**Created**: 2026-05-30
-
-**Status**: Current State (reverse-specified from docs, hammerkit 1.6.0)
-
-**Input**: Existing behavior documented in `docs/build-file/references.md`
-
-## User Scenarios & Testing *(mandatory)*
-
-### User Story 1 - Run a task from a referenced sub-project (Priority: P1)
-
-A developer has a monorepo with multiple sub-directories, each containing its own build file. They declare a `references:` map in the root build file, giving each sub-project a short alias. They can then invoke tasks in those sub-projects from the CLI using the `<alias>:<task>` syntax, or declare them as dependencies in root tasks.
-
-**Why this priority**: References are the primary mechanism for composing multi-project builds from a single entry-point build file.
-
-**Independent Test**: Create a root build file with a reference to a sub-directory build file. Run `hammerkit <alias>:<task>` and confirm the task in the sub-project executes.
-
-**Acceptance Scenarios**:
-
-1. **Given** a root build file declares `references: { foo: project/foo }`, and `project/foo/.hammerkit.yaml` contains a task named `example`, **When** the user runs `hammerkit foo:example`, **Then** the `example` task from `project/foo` executes.
-2. **Given** a root task declares `foo:example` in its `deps:`, **When** that root task runs, **Then** `foo:example` is executed as a prerequisite with the working directory fixed to `project/foo`.
-
-### Edge Cases
-
-- The working directory for tasks in a referenced build file is fixed to the directory where the referenced build file resides, not the directory of the referencing build file.
-- Top-level `envs:` from the referencing build file are not visible to tasks in the referenced build file.
-- Circular references (A references B which references A) are not discussed in the docs; behavior is assumed to be an error or undefined.
-
-## Requirements *(mandatory)*
-
-### Functional Requirements
-
-- **FR-001**: The build file MUST support a top-level `references:` map where each key is an alias and each value is a path to another project directory containing a build file.
-- **FR-002**: Tasks from a referenced build file MUST be addressable using the `<alias>:<task-name>` notation from the CLI.
-- **FR-003**: Tasks from a referenced build file MUST be usable as dependency entries in the referencing build file's task `deps:` list using the `<alias>:<task-name>` notation.
-- **FR-004**: The working directory for tasks executing in a referenced build file MUST be the directory of that referenced build file, not the directory of the referencing file.
-
-### Key Entities
-
-- **Reference**: A named entry in the `references:` map; the key is the alias used to prefix task names, the value is the relative path to the sub-project directory.
-
-## Success Criteria *(mandatory)*
-
-### Measurable Outcomes
-
-- **SC-001**: A task in a referenced build file is successfully invoked via `hammerkit <alias>:<task>` and executes with the working directory set to the referenced project directory.
-- **SC-002**: A task in the root build file that lists `<alias>:<task>` as a dependency causes that referenced task to run before the root task's commands execute.
-
-## Assumptions
-
-- The path in the `references:` value points to a directory, and hammerkit locates the build file (`build.yaml` or `.hammerkit.yaml`) within that directory automatically.
-- Reference paths are relative to the directory of the build file containing the `references:` block.
-- Deeply nested references (a reference to a build file that itself references another) are assumed to be supported, though not explicitly documented.

package/specs/build-file/spec.md

@@ -1,62 +0,0 @@
-# Feature Specification: Build File: Overview
-
-**Feature Branch**: `001-current-state-specs`
-
-**Created**: 2026-05-30
-
-**Status**: Current State (reverse-specified from docs, hammerkit 1.6.0)
-
-**Input**: Existing behavior documented in `docs/build-file/README.md`
-
-## User Scenarios & Testing *(mandatory)*
-
-### User Story 1 - Define a project build file (Priority: P1)
-
-A developer creates a `build.yaml` (or `.hammerkit.yaml`) file at the root of their project directory. They declare top-level environment variables, one or more named tasks, references to sub-projects, and includes for shared task files. They then invoke tasks by name via the hammerkit CLI.
-
-**Why this priority**: The build file is the central configuration artifact; all other hammerkit features depend on it.
-
-**Independent Test**: Create a minimal build file with a single task and verify `hammerkit <task>` executes it.
-
-**Acceptance Scenarios**:
-
-1. **Given** a project directory, **When** a `build.yaml` file is placed there with a valid `tasks:` block, **Then** hammerkit discovers and executes named tasks from that file via the CLI.
-2. **Given** a build file with a top-level `envs:` block, **When** a task is run, **Then** the declared environment variables are available to the task commands.
-3. **Given** a build file with `references:` and `includes:` blocks, **When** hammerkit starts, **Then** it loads the referenced and included build files and makes their tasks available under the appropriate namespaced names.
-
-### Edge Cases
-
-- A build file with no `tasks:` block is valid but produces no executable targets.
-- The filename may be `build.yaml` or `.hammerkit.yaml`; behavior is identical.
-- Top-level `envs:` are scoped to the build file where they are declared and do not propagate to referenced or included files.
-
-## Requirements *(mandatory)*
-
-### Functional Requirements
-
-- **FR-001**: The system MUST read build configuration from a YAML file named `build.yaml` or `.hammerkit.yaml` located in the project directory.
-- **FR-002**: The build file MUST support a top-level `envs:` map for declaring environment variables shared across all tasks in that file.
-- **FR-003**: The build file MUST support a top-level `tasks:` map where each key is a task name and the value is the task configuration.
-- **FR-004**: The build file MUST support a top-level `references:` map pointing to other build files in sub-directories.
-- **FR-005**: The build file MUST support a top-level `includes:` map pointing to shared build files whose tasks are merged under a namespace.
-- **FR-006**: Tasks declared in a build file MUST be invocable by name via the hammerkit CLI.
-
-### Key Entities
-
-- **Build File**: A YAML file (`build.yaml` / `.hammerkit.yaml`) containing `envs`, `tasks`, `references`, and `includes` top-level keys.
-- **Task**: A named unit of work inside the `tasks:` map; may declare commands, dependencies, source files, and generated outputs.
-- **Reference**: A named pointer to another project directory containing its own build file.
-- **Include**: A named pointer to a shared build YAML file whose tasks are reused with the working directory of the including file.
-
-## Success Criteria *(mandatory)*
-
-### Measurable Outcomes
-
-- **SC-001**: A build file with all four top-level sections (`envs`, `tasks`, `references`, `includes`) loads without errors and all tasks are accessible via the CLI.
-- **SC-002**: Environment variables defined in the top-level `envs:` block are resolved correctly within tasks in the same file and are not visible in referenced or included files.
-
-## Assumptions
-
-- The primary filename used in examples is `.hammerkit.yaml`; `build.yaml` is also accepted based on the docs description.
-- The `caches:` top-level key (introduced in 1.6.0) exists in the build file schema but is covered by its own spec page.
-- Task-level details (image, cmds, deps, src, generates) are covered by the Task spec pages, not this overview.

package/specs/cli/clean/spec.md

@@ -1,85 +0,0 @@
-# Feature Specification: CLI: clean
-
-**Feature Branch**: `001-current-state-specs`
-
-**Created**: 2026-05-30
-
-**Status**: Current State (reverse-specified from docs, hammerkit 1.6.0)
-
-**Input**: Existing behavior documented in `docs/cli/clean.md`
-
-## User Scenarios & Testing *(mandatory)*
-
-### User Story 1 - Remove generated outputs and local cache state for a clean rebuild (Priority: P1)
-
-A developer suspects their build is producing stale results due to a previous cached state. They run `hammerkit clean` to delete all generated directories and files as well as hammerkit's per-task cache state for the current checkout, then re-run tasks to verify everything builds from scratch.
-
-**Why this priority**: The primary purpose of `clean` is to reset local state so that builds are fully reproducible without prior artifacts.
-
-**Independent Test**: Run a task that produces a `generates` output. Run `hammerkit clean`. Confirm the generated output no longer exists and that hammerkit re-executes the task on the next run regardless of unchanged inputs.
-
-**Acceptance Scenarios**:
-
-1. **Given** tasks have been run and generated outputs and cache state exist, **When** `hammerkit clean` is run, **Then** all generated outputs and per-task local cache state are removed.
-
-2. **Given** `hammerkit clean` has completed, **When** a task is run again with unchanged inputs, **Then** hammerkit re-executes the task because the local cache state is absent.
-
-### User Story 2 - Drop stored remote/backend cache results to force a full rebuild (Priority: P2)
-
-A developer encounters a persistent caching issue and needs to force the next run to rebuild from scratch even against a configured cache backend (local result store or remote, e.g. S3). They run `hammerkit clean --cache` to also purge stored results from the backend.
-
-**Why this priority**: The `--cache` flag addresses a deeper reset need when the standard clean is insufficient due to a populated cache backend.
-
-**Independent Test**: Configure a cache backend. Run tasks so results are stored in the backend. Run `hammerkit clean --cache`. Confirm the backend has no stored results for the project and that the next run rebuilds all tasks.
-
-**Acceptance Scenarios**:
-
-1. **Given** a configured cache backend with stored task results, **When** `hammerkit clean --cache` is run, **Then** the stored results in the backend (local `~/.hammerkit/remote-cache` or remote) are deleted in addition to generated outputs and local cache state.
-
-2. **Given** `--cache` is omitted, **When** `hammerkit clean` is run, **Then** stored results in the cache backend are preserved; only local generated outputs and per-task cache state are removed.
-
-### User Story 3 - Clean a subset of tasks and services using label filters (Priority: P2)
-
-A developer wants to clean only a specific subset of tasks without affecting others. They use `--filter` or `--exclude` with label selectors to target or omit specific tasks and services.
-
-**Why this priority**: Label-scoped clean reduces disruption to unrelated tasks in large build files.
-
-**Independent Test**: Tag two tasks with different labels. Run both. Run `hammerkit clean --filter <label>`. Confirm only the filtered task's outputs and cache state are removed while the other task's outputs remain.
-
-**Acceptance Scenarios**:
-
-1. **Given** tasks are labeled, **When** `hammerkit clean --filter <label>` is run, **Then** only the tasks and services matching the label are cleaned.
-
-2. **Given** tasks are labeled, **When** `hammerkit clean --exclude <label>` is run, **Then** tasks and services matching the label are skipped and all others are cleaned.
-
-### Edge Cases
-
-- Running `hammerkit clean` when no tasks have been run (no generated outputs, no cache state) should complete without error.
-- `hammerkit clean --cache` removes the local result store at `~/.hammerkit/remote-cache` or a configured remote backend, not just the per-checkout cache state.
-- Label filters apply to both tasks and services, consistent with their behavior in other commands.
-
-## Requirements *(mandatory)*
-
-### Functional Requirements
-
-- **FR-001**: System MUST remove all generated outputs (files and directories declared via `generates`) for all tasks and services in the current checkout when `hammerkit clean` is run.
-- **FR-002**: System MUST remove the per-task local cache state for the current checkout when `hammerkit clean` is run.
-- **FR-003**: When `--cache` is supplied, system MUST additionally delete stored results from the configured cache backend (defaulting to `~/.hammerkit/remote-cache` for local backends).
-- **FR-004**: System MUST support `-f`/`--filter` and `-e`/`--exclude` label options to restrict which tasks and services are cleaned.
-- **FR-005**: System MUST complete without error when there are no generated outputs or cache state to remove.
-
-## Success Criteria *(mandatory)*
-
-### Measurable Outcomes
-
-- **SC-001**: After `hammerkit clean`, no generated output directories or files from any task's `generates` field exist in the working tree.
-- **SC-002**: After `hammerkit clean`, running any task re-executes it fully regardless of whether its inputs have changed.
-- **SC-003**: After `hammerkit clean --cache`, the cache backend contains no stored results for the project and the next run rebuilds all tasks from source.
-- **SC-004**: After `hammerkit clean --filter <label>`, only tasks matching the label have their outputs and cache state removed; all other task outputs remain intact.
-
-## Assumptions
-
-- "Per-task cache state" refers to the hammerkit-internal tracking of input hashes used to determine whether a task is up to date; this is distinct from stored build results in the cache backend.
-- The `--cache` flag targets whatever backend is configured in the build file's `caches` section, defaulting to the local result store at `~/.hammerkit/remote-cache`.
-- The `clean` command does not prompt for confirmation; it is destructive by design.
-- There is no `--dry-run` option documented; the command always performs the deletion.

package/specs/cli/down/spec.md

@@ -1,85 +0,0 @@
-# Feature Specification: CLI: down
-
-**Feature Branch**: `001-current-state-specs`
-
-**Created**: 2026-05-30
-
-**Status**: Current State (reverse-specified from docs, hammerkit 1.6.0)
-
-**Input**: Existing behavior documented in `docs/cli/down.md`
-
-## User Scenarios & Testing *(mandatory)*
-
-### User Story 1 - Stopping all running services (Priority: P1)
-
-A developer has finished their work session and wants to free the resources held by services that were started with `hammerkit up` (foreground or daemon). They run `hammerkit down` and all services defined in the build file are stopped.
-
-**Why this priority**: `down` is the natural complement to `up` and the primary way to cleanly release containerized service resources.
-
-**Independent Test**: Start services with `hammerkit up --daemon`, then run `hammerkit down` and verify that all service containers are no longer running.
-
-**Acceptance Scenarios**:
-
-1. **Given** services started with `hammerkit up --daemon`, **When** the user runs `hammerkit down`, **Then** all services defined in the build file are stopped and exit cleanly.
-
-2. **Given** services started with `hammerkit up` (foreground, now interrupted), **When** the user runs `hammerkit down`, **Then** any remaining service containers are stopped.
-
-3. **Given** no services currently running, **When** the user runs `hammerkit down`, **Then** the command exits with code 0 without error.
-
-### User Story 2 - Stopping a subset of services by label (Priority: P2)
-
-A developer is running multiple services and wants to stop only a specific subset without affecting others. They use `--filter` or `--exclude` to target the relevant services.
-
-**Why this priority**: Label filtering is consistent across all service-related commands and supports fine-grained lifecycle control in complex builds.
-
-**Independent Test**: Start two labeled services, run `hammerkit down -f <label>` matching only one, and verify the other remains running.
-
-**Acceptance Scenarios**:
-
-1. **Given** multiple services with different labels, **When** the user runs `hammerkit down -f <label>`, **Then** only services matching the label are stopped; others remain running.
-
-2. **Given** multiple services with different labels, **When** the user runs `hammerkit down -e <label>`, **Then** services matching the excluded label are not stopped; all others are stopped.
-
-### User Story 3 - Stopping services in a named environment (Priority: P3)
-
-A developer has services running in a Kubernetes environment and wants to stop them without affecting local Docker services. They pass `--env <name>` to target that environment.
-
-**Why this priority**: Multi-environment support is consistent with `up` but is a power-user scenario.
-
-**Independent Test**: Given services running in a named Kubernetes environment, run `hammerkit down --env <name>` and verify those services stop while local Docker services are unaffected.
-
-**Acceptance Scenarios**:
-
-1. **Given** services running in a named environment, **When** the user runs `hammerkit down --env <name>`, **Then** services in that environment are stopped.
-
-### Edge Cases
-
-- `hammerkit down` with no running services must not error.
-- `hammerkit down -f <label>` where no services match the label must exit with code 0 without affecting other services.
-- `--filter` and `--exclude` used together must apply both constraints; services matching both conditions are excluded.
-
-## Requirements *(mandatory)*
-
-### Functional Requirements
-
-- **FR-001**: System MUST stop all services defined in the build file when `hammerkit down` is run without filter options.
-- **FR-002**: System MUST support label-based inclusion filtering via `-f / --filter <key=value>` to stop only matching services.
-- **FR-003**: System MUST support label-based exclusion filtering via `-e / --exclude <key=value>` to skip stopping matching services.
-- **FR-004**: System MUST support an `--env <name>` option to stop services in a configured named environment.
-- **FR-005**: System MUST exit with code 0 when no services are running (idempotent stop).
-
-## Success Criteria *(mandatory)*
-
-### Measurable Outcomes
-
-- **SC-001**: After `hammerkit down`, no service containers defined in the build file remain in a running state.
-- **SC-002**: `hammerkit down` exits with code 0 regardless of whether services were running before the command.
-- **SC-003**: With `-f <label>`, only services bearing that label are stopped; services with other labels continue running.
-- **SC-004**: With `--env <name>`, only services in the named environment are stopped; services in other environments are unaffected.
-
-## Assumptions
-
-- `hammerkit down` targets the same set of services as the corresponding `hammerkit up` invocation when no filters are applied.
-- The command does not require that services were started specifically via `hammerkit up`; it stops matching service containers regardless of how they were started.
-- `down` has no `--daemon`, `--concurrency`, `--watch`, `--log`, or `--cache` options (these do not appear in the documented option list).
-- Stopping a service that is not running is treated as a success (idempotent), consistent with the "no error on empty" edge case documented implicitly.

package/specs/cli/execute/spec.md

@@ -1,101 +0,0 @@
-# Feature Specification: CLI: execute
-
-**Feature Branch**: `001-current-state-specs`
-
-**Created**: 2026-05-30
-
-**Status**: Current State (reverse-specified from docs, hammerkit 1.6.0)
-
-**Input**: Existing behavior documented in `docs/cli/execute.md`
-
-## User Scenarios & Testing *(mandatory)*
-
-### User Story 1 - Running a task by name (Priority: P1)
-
-A developer wants to build a specific artifact. They run `hammerkit <task-name>` (or `hammerkit run <task-name>`) and hammerkit executes that task and all its declared dependencies inside the appropriate containers.
-
-**Why this priority**: Executing tasks is the core purpose of the tool; all other features support this.
-
-**Independent Test**: Given a build file with a task named `example`, run `hammerkit example` and verify it completes successfully and produces the expected output.
-
-**Acceptance Scenarios**:
-
-1. **Given** a build file with a task `build`, **When** the user runs `hammerkit build`, **Then** hammerkit executes the `build` task (and its dependencies) and exits with code 0 on success.
-
-2. **Given** a build file with a task `build`, **When** the user runs `hammerkit run build`, **Then** the result is identical to running `hammerkit build`.
-
-3. **Given** a task name that does not exist in the build file, **When** the user runs `hammerkit <nonexistent>`, **Then** hammerkit exits with a non-zero code and a meaningful error message.
-
-### User Story 2 - Filtering tasks by labels (Priority: P2)
-
-A monorepo developer wants to run only the iOS build tasks. They use `--filter` to include only tasks with a matching label or `--exclude` to skip tasks with a given label, so unrelated tasks are not executed.
-
-**Why this priority**: Label-based filtering is a key scalability feature for large builds with many tasks.
-
-**Independent Test**: Given a build file with tasks labeled `build=ios` and `build=android`, run `hammerkit -f build=ios` and verify only the iOS tasks (and their dependencies) execute.
-
-**Acceptance Scenarios**:
-
-1. **Given** tasks with label `type=build` and tasks without that label, **When** the user runs `hammerkit -f type=build`, **Then** only tasks matching `type=build` are executed; dependent tasks without that label may still run to satisfy dependencies.
-
-2. **Given** tasks with label `build=ios`, **When** the user runs `hammerkit -e build=ios`, **Then** tasks with `build=ios` are excluded; if a dependent task also matches the excluded label, it is excluded too.
-
-3. **Given** multiple label filters, **When** the user provides multiple `-f` arguments, **Then** only tasks matching all specified labels are included.
-
-### User Story 3 - Controlling concurrency, caching, and log mode (Priority: P3)
-
-A developer running on a slow machine wants to limit parallel workers, or a CI engineer wants checksum-based caching and grouped log output. They pass the relevant flags to tune hammerkit's behavior for their environment.
-
-**Why this priority**: These are power-user options that improve CI reliability and local performance but are not needed for basic usage.
-
-**Independent Test**: Run `hammerkit run <task> --concurrency 1` and verify tasks execute sequentially (no interleaved log lines from parallel workers).
-
-**Acceptance Scenarios**:
-
-1. **Given** a build file with multiple independent tasks, **When** the user runs `hammerkit -c 1`, **Then** tasks execute one at a time rather than in parallel.
-
-2. **Given** a CI environment, **When** hammerkit detects CI, **Then** `--log` defaults to `live` and `--cache` defaults to `checksum` without requiring explicit flags.
-
-3. **Given** a local (non-CI) environment, **When** hammerkit runs without explicit `--log` or `--cache` flags, **Then** `--log` defaults to `interactive` and `--cache` defaults to `modify-date`.
-
-4. **Given** a task with `src` files, **When** `--cache none` is specified, **Then** the task runs unconditionally without checking whether inputs have changed.
-
-5. **Given** a task with `src` files that have not changed, **When** `--watch` is specified, **Then** hammerkit watches those files and re-executes the task when they change.
-
-### Edge Cases
-
-- Specifying both `--filter` and `--exclude` with overlapping labels must resolve deterministically (exclude takes precedence for matched tasks).
-- `--concurrency 0` or negative values should be rejected with a clear error.
-- `--env <name>` is accepted but its behavior is defined by the environment configuration, not by the execute command itself.
-
-## Requirements *(mandatory)*
-
-### Functional Requirements
-
-- **FR-001**: System MUST execute a task by name when the user supplies the task name as the first argument (with or without the explicit `run` subcommand).
-- **FR-002**: System MUST execute all declared dependency tasks before the named task.
-- **FR-003**: System MUST support label-based inclusion filtering via `-f / --filter <key=value>` where only tasks matching the label are directly executed (dependencies may still run).
-- **FR-004**: System MUST support label-based exclusion filtering via `-e / --exclude <key=value>` where tasks (and their dependents) matching the label are skipped.
-- **FR-005**: System MUST support a `-c / --concurrency <number>` option controlling the number of parallel worker threads (default: 4).
-- **FR-006**: System MUST support a `-w / --watch` flag that re-executes tasks when their source files change.
-- **FR-007**: System MUST support a `--cache <method>` option with choices `checksum`, `modify-date`, and `none`.
-- **FR-008**: System MUST support a `-l / --log <mode>` option with choices `interactive`, `live`, and `grouped`.
-- **FR-009**: System MUST default `--log` to `interactive` and `--cache` to `modify-date` outside CI, and to `live` and `checksum` inside CI.
-- **FR-010**: System MUST support an `--env <name>` option to target a configured named environment.
-
-## Success Criteria *(mandatory)*
-
-### Measurable Outcomes
-
-- **SC-001**: `hammerkit <task>` and `hammerkit run <task>` produce identical exit codes and output for the same task.
-- **SC-002**: With `-f type=build`, only tasks bearing the `type=build` label are directly invoked; the set of executed tasks is smaller than running without the filter.
-- **SC-003**: With `-e build=ios`, no task bearing `build=ios` appears in the execution log.
-- **SC-004**: With `-c 1`, task execution log lines are never interleaved across concurrent workers.
-- **SC-005**: With `--cache none`, a task runs even when no source files have changed since the last run.
-
-## Assumptions
-
-- `hammerkit` with no subcommand and no task name runs all tasks (or the default task if one is defined); the docs show a task name is required for named execution.
-- `--filter` and `--exclude` accept `key=value` pairs; partial-key matching (e.g., filtering by key name only) is not documented and assumed unsupported.
-- The `--watch` flag watches the `src` files declared on the task; the exact file-watching mechanism is an implementation detail.
-- CI is detected automatically via standard CI environment variables (e.g., `CI=true`); this is an informed guess not explicitly stated in the docs.

package/specs/cli/init/spec.md

@@ -1,64 +0,0 @@
-# Feature Specification: CLI: init
-
-**Feature Branch**: `001-current-state-specs`
-
-**Created**: 2026-05-30
-
-**Status**: Current State (reverse-specified from docs, hammerkit 1.6.0)
-
-**Input**: Existing behavior documented in `docs/cli/init.md`
-
-## User Scenarios & Testing *(mandatory)*
-
-### User Story 1 - Bootstrapping a new project (Priority: P1)
-
-A developer starts a brand-new project and wants to adopt hammerkit. They run `hammerkit init` in the project root, which creates a ready-to-edit `.hammerkit.yaml` with a working example task and appends the hammerkit cache directory to `.gitignore` so build artifacts are not accidentally committed.
-
-**Why this priority**: `init` is the mandatory first step for every new hammerkit user; without it the rest of the tool cannot be used.
-
-**Independent Test**: In an empty directory, run `hammerkit init` and verify that `.hammerkit.yaml` and `.gitignore` are created (or updated) with the documented content.
-
-**Acceptance Scenarios**:
-
-1. **Given** an empty directory with no existing build file, **When** the user runs `hammerkit init`, **Then** a `.hammerkit.yaml` file is created containing an `envs: {}` block, a `tasks:` block with an `example` task using the `alpine` image and the command `echo "it's Hammer Time!"`.
-
-2. **Given** an empty directory with no existing `.gitignore`, **When** the user runs `hammerkit init`, **Then** a `.gitignore` file is created containing the entry `.hammerkit`.
-
-3. **Given** a directory that already has a `.gitignore`, **When** the user runs `hammerkit init`, **Then** the `.hammerkit` entry is appended to the existing `.gitignore` without overwriting other entries.
-
-4. **Given** a directory that already has a `.hammerkit.yaml`, **When** the user runs `hammerkit init`, **Then** the command succeeds (or warns) without overwriting the existing build file.
-
-### Edge Cases
-
-- If the user lacks write permissions in the working directory, `init` must exit with a non-zero code and a meaningful error message.
-- Running `init` when a `.hammerkit.yaml` already exists must not destroy existing configuration.
-
-## Requirements *(mandatory)*
-
-### Functional Requirements
-
-- **FR-001**: System MUST create a `.hammerkit.yaml` file in the current working directory when `hammerkit init` is run and no build file exists.
-- **FR-002**: The generated `.hammerkit.yaml` MUST contain an `envs: {}` key and a `tasks:` key with at least one example task using the `alpine` image.
-- **FR-003**: System MUST create or update a `.gitignore` file in the current working directory to include the `.hammerkit` cache directory entry.
-- **FR-004**: System MUST print confirmation output indicating each file that was created or updated, including the file path.
-
-### Key Entities
-
-- **Build file (`.hammerkit.yaml`)**: The hammerkit project configuration file. Created by `init` with a minimal, runnable example task.
-- **Cache directory entry (`.hammerkit`)**: The directory hammerkit uses for local caching; excluded from version control via `.gitignore`.
-
-## Success Criteria *(mandatory)*
-
-### Measurable Outcomes
-
-- **SC-001**: After `hammerkit init`, the file `.hammerkit.yaml` exists in the working directory and is parseable as valid YAML with the documented structure.
-- **SC-002**: After `hammerkit init`, the file `.gitignore` in the working directory contains the line `.hammerkit`.
-- **SC-003**: `hammerkit init` exits with code 0 and prints at least two confirmation lines (one per created/updated file).
-- **SC-004**: Running `hammerkit run example` immediately after `hammerkit init` in a Docker-enabled environment succeeds without manual editing.
-
-## Assumptions
-
-- `init` creates files relative to the current working directory (not a project-root detection heuristic).
-- The console confirmation output format is a checkmark prefix followed by the absolute path of each file, as shown in the docs example.
-- If `.hammerkit.yaml` already exists, `init` skips creation rather than overwriting; this is an informed guess based on the "non-destructive bootstrap" intent.
-- The `--file` global option does not affect where `init` writes the build file; it always writes `.hammerkit.yaml`.