jan-cli 0.20.0

YAML-defined CLI trees with progressive help, optional exec aliases, merged extra specs, and SQLite audit logging keyed by git branch
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72

name: jan-cli
description: |
  YAML-defined CLI command trees for agents and humans:
  - Nested subcommands with progressive `--help` at each level
  - Leaf nodes that delegate to real programs (`exec.argv`)
  - Optional passthrough of extra CLI args (`exec.passthrough`)
  - Remote scripts via `exec.url` + `exec.sha256` (HTTPS fetch, hash verify, TTL cache)
  - Remote YAML `include: {url, sha256}` and `jan use https://…/bundle.zip --sha256`
  - Script `path`, `dependencies` (other scripts on PATH), `requires` (external tools), and `env`
  - Preferred directory via `jan use` (XDG config); `jan --help` lists live subcommands
  - SQLite audit log of invocations keyed by git branch (override with `--branch` / `JAN_BRANCH`)
  - `jan bundle` / `jan alias` for portable spec export and shell aliases
  - `jan list` / `search` / `show` / `validate` / `audit` over the preferred tree
  - MkDocs documentation site (`docs/`, `mkdocs.yml`)
language: rust
tags:
  - rust
  - cli
  - yaml
  - sqlite
  - agents
scripts:
  build:
    command: cargo build --release
  test:
    command: cargo test
  fmt:
    command: cargo fmt
  clippy:
    command: cargo clippy
  run:
    command: cargo run --bin jan -- --help
  package:
    command: cargo package
  publish:
    command: cargo publish
  release:
    command: ./scripts/release.sh
  release-dry-run:
    command: ./scripts/release.sh --dry-run
  release-minor:
    command: ./scripts/release.sh --minor
  release-major:
    command: ./scripts/release.sh --major
  docs-serve:
    command: ./serve.sh
  docs-build:
    command: ./serve.sh build
roadmap:
  done:
    - "YAML-defined nested CLI command trees with progressive --help"
    - "Leaf exec: argv, passthrough, remote url+sha256, include, jan use bundle.zip"
    - "Script path, dependencies, requires, and env in specs"
    - "Preferred directory via jan use (XDG config); jan --help lists live subcommands"
    - "SQLite audit log keyed by git branch (--branch / JAN_BRANCH override)"
    - "jan bundle / alias for portable spec export and shell aliases"
    - "jan list / search / show / validate / audit over the preferred tree"
    - "MkDocs documentation site (docs/, mkdocs.yml)"
    - "Jan cron daemon: long-running scheduler; jan cron start/stop front end (Gradle-style)"
    - "Sub-minute cron: 100ms daemon ticks; 5/6/7-field cron YAML; systemd user unit"
    - "Cache file tree in daemon: schedules parsed once; tick path is memory-only; jan cron refresh"
  in_progress: []
  todo:
    - "Unix domain socket to Unifier: Jan daemon listens on unifier .daemon/events.sock; wakeup notices include recipient + message id so Jan can wake that agent on the next tick"
    - "Dynamic tick agents: unifier events/messages add agents to next tick by name regardless of cron schedule"
    - "Span-tree logging: integrate with unifier log for tracing inside Jan cron scripts"
    - "Report export: Jan reports exportable as Unifier HTML via daemon for formatting and interactivity"
    - "Tick-based agent specs: three-phase sense/decide/act lockstep, scheduling modes (serial, pipelined, drop-on-overflow)"
    - "Agent definitions: hot state between ticks, checkpoint watermarks, differential sensing hooks"
    - "Inter-agent coordination via Unifier blackboard; global synchronous tick vs independent local tick schedules"
    - "Max concurrent job queue: defer n+1 runs under load; log queued work"
    - "Factorio factory model: Jan schedules isolated sense/filter/act arms as part of a coordinated system goal"