eric/narratio
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 15 Wiki Activity

Consolidated addition, removal, and listing of locks under a single narratio locks command

Browse Source
This commit is contained in:
Eric Rakestraw
2026-05-21 19:36:14 -05:00
parent 135407ba7c
commit 870c2d69d5
7 changed files with 282 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files

53
docs/cli.md
View File

@@ -23,9 +23,7 @@ Implemented commands:
- `session validate`: run read-only preflight checks for a session.
- `session init`: create local or remote `session.yml`.
- `artifacts list`: list effective artifact source IDs.
- `locks`: list effective archive promotion locks.
- `lock`: add or update a remote session lock.
- `unlock`: remove a remote session lock.
- `locks`: list, add, and remove archive promotion locks.
Unknown commands print usage and exit non-zero.
@@ -136,17 +134,17 @@ Valid stage names:
- `--previous-session-id <value>`
- `--remote`: check promoted remote object availability.
### `locks`, `lock`, `unlock`
### `locks`
- `--config <path>`
- `--campaign <path>`
- `--session <path>`
- `--session-id <value>`
- `--previous-session-id <value>`
- `lock <source>` positional source ID.
- `lock --reason <text>` optional remote lock reason.
- `lock --force` updates an existing remote lock.
- `unlock <source>` positional source ID.
- `--session-id <value>`: required for list, add, and remove.
- `--config <path>`: optional explicit `pipeline.yml` path.
- `--campaign <path>`: optional explicit `campaign.yml` path.
- `--session <path>`: optional explicit `session.yml` path.
- `--previous-session-id <value>`: optional session template value.
- `add <source>`: add a remote lock for one artifact or transcript source.
- `add --reason <text>`: record an optional remote lock reason.
- `add --force`: update the reason for an existing remote lock.
- `remove <source>`: remove one remote lock.
## Command Reference
@@ -291,25 +289,34 @@ narratio artifacts list [--config <pipeline.yml>] [--campaign <campaign.yml>] [-
`--remote` checks promoted top-level object availability through the storage adapter.
### `locks`, `lock`, and `unlock`
### `locks`
Purpose:
- Inspect and mutate source-based archive promotion locks.
- Inspect and mutate source-based archive promotion locks for one session.
Syntax:
```bash
narratio locks [--config <pipeline.yml>] [--campaign <campaign.yml>] [--session <session.yml>] [--session-id <id>]
narratio lock [flags] <source>
narratio unlock [flags] <source>
narratio locks --session-id <id>
narratio locks add --session-id <id> [--reason <text>] [--force] <source>
narratio locks remove --session-id <id> <source>
```
Behavior:
- static locks from `pipeline.archive.locks` and remote locks from `{session_prefix}/locks.yml` are merged.
- static locks win when sources duplicate remote locks.
- `lock` writes or updates only remote locks.
- `unlock` removes only remote locks and cannot remove static pipeline locks.
- `lock --force` is required to update an existing remote lock reason.
- `--session-id` is required for list, add, and remove.
- optional `--config`, `--campaign`, and `--session` override default config discovery.
- list mode prints effective locks from static `pipeline.archive.locks` and remote `{session_prefix}/locks.yml`.
- `locks add` writes only the remote lock store and fails if the source is already locked by pipeline config.
- `locks remove` removes only remote locks and cannot remove static pipeline locks.
- `locks add --force` is required to update an existing remote lock reason.
Examples:
```bash
narratio locks --session-id 2026-04-04
narratio locks add --session-id 2026-04-04 --reason "manual transcript review" narratio.transcript.trimmed
narratio locks remove --session-id 2026-04-04 narratio.transcript.trimmed
```
### `run-stage`