Skip to content

Releases

v0.1.6-rc2

v0.1.6-rc2 Pre-release
Pre-release

Choose a tag to compare

@zhao-bears zhao-bears released this 17 Nov 07:50
7d0263d

v0.1.6-rc2 (prerelease)

Second prerelease of PUDA CLI 0.1.6. Not marked Latest; install it explicitly:

puda update v0.1.6-rc2
puda skills update

Changes since v0.1.6-rc1

Healthcheck

  • puda healthcheck prints exactly one JSON report and nothing else.
  • SDK compatibility is part of that report as a compatibility object after gateways (advisory only; never changes status or exit code).
  • Each transport error is reported once, on the affected server. Dependent checks carry status/reason: not_checked when they could not run, failed when they ran and failed.
  • JetStream and discovery permission errors are captured in the report instead of leaking to stderr.
  • An unhealthy report exits 1 with no extra Error: line or stderr prose. Config and output errors are still shown.

Identity

  • Login is optional. Commands that need an identity create a default one: your OS username plus a generated user ID, marked user.default: true (shown by puda config list).
  • puda login --username <name> replaces the default identity and keeps its user ID. Simulated authentication messages were removed.
  • puda logout clears only the user identity; NATS profiles and other settings are kept.
  • An unreadable or invalid global config is never deleted; commands return an error and leave the file unchanged.

Other CLI fixes

  • puda init --help now says it creates puda.config.

Skills

Skills are versioned with the CLI; run puda skills update after updating.

  • Recovery after a failed protocol: puda machine reset, then rerun the protocol from the failed step with --steps <N>-.
  • puda-manual-ui is framework-agnostic: a UI only needs to drive puda machine start, run and complete, and takes livestream URLs from puda machine info. Streamlit is an example, not a requirement.
  • puda-deployment maps puda healthcheck report fields to troubleshooting steps.
  • Fixed outdated guidance and registry keys; removed CLI version gates and the legacy experiment.md marker.
  • Removed unused puda-data code and duplicated command lists; skills point to puda <command> --help instead.

Upgrading from 0.1.5

Follow the v0.1.6-rc1 upgrade steps. In short:

  1. Stop database writers and back up the project database with SQLite's backup API.
  2. puda update v0.1.6-rc2.
  3. From the project root, apply and confirm the additive migration (run.steps, run.notes):
    puda db exec "SELECT name FROM pragma_table_info('run') WHERE name IN ('steps', 'notes')"
  4. puda skills update (installs skills from this tag; same-name skills from PUDAP/skills are replaced, legacy-only skills are left in place).

From v0.1.6-rc1, only steps 2 and 4 are needed.

Prerelease caveat

This binary reports version 0.1.6-rc2. The compatibility policy only matches stable CLI versions, so SDK compatibility is reported as unknown.

Python SDK

SDK 0.0.22 is a separate PyPI release (see the v0.1.6-rc1 notes); this CLI neither requires nor installs it.

Verification

  • Built with GoReleaser from tag v0.1.6-rc2 (commit 7d0263d); all binaries report 0.1.6-rc2. Root and CLI go vet/go test passed (CLI tests with a local NATS server, no skips). Archive checksums verified.
  • Default puda skills install installed all seven skills from the v0.1.6-rc2 tag in an isolated home; files matched the tag.
  • healthcheck against an unreachable server: one JSON report, exit 1, empty stderr. config list in a fresh home shows the default identity.
  • Not tested in this round: hardware, encrypted (TLS) brokers, live edges.

v0.1.6-rc1

v0.1.6-rc1 Pre-release
Pre-release

Choose a tag to compare

@zhao-bears zhao-bears released this 17 Nov 03:45

v0.1.6-rc1 (prerelease)

Prerelease of PUDA CLI 0.1.6. Not marked Latest; install it explicitly:

puda update v0.1.6-rc1
puda skills update

Highlights

  • Skills are versioned with the CLI. The seven PUDA agent skills now live in this repo (skills/) and are tagged with each CLI release. puda skills install / update install the skills from the installed CLI's release tag, so skills always match the CLI they describe. Run puda skills update after every puda update.
  • Run notes. puda protocol note --run <run-id> --text <summary> appends a timestamped summary (Markdown links to reports, plots and data are kept) to a protocol run. run.steps records the --steps selection used.
  • Python SDK compatibility advisories. machine list, machine info, healthcheck and puda update check each responding edge's reported SDK version against compatibility.json. Advisory only: results and exit codes are unchanged.

Skills

  • Installed from PUDAP/puda at this release's tag (v0.1.6-rc1) instead of the separate PUDAP/skills repository.
  • --ref <branch-or-tag> selects another version, e.g. --ref main. A missing tag fails instead of falling back to main.
  • Same-name skills from PUDAP/skills are replaced; back up local edits first. Skills that exist only in the old repo (e.g. puda-memory) are left in place. Streamlit skills are no longer installed automatically.
  • Details: docs/skills-migration.md.

Compatibility advisories

  • Policy: compatibility.json at the repo root, with inclusive ranges: CLI 0.1.0–0.1.6 with SDK 0.0.17–0.0.22; legacy CLI 0.0.0–0.0.36 with SDK 0.0.15–0.0.16 (declared, not tested).
  • Uses the version each running edge reports, not locally installed packages. Unknown, development or unparseable versions report unknown; edges that don't respond can't be checked.
  • puda update checks the target release's own policy before installing and lists affected machines.
  • Prerelease caveat: this binary reports version 0.1.6-rc1, and the policy only matches stable CLI versions, so its advisories report SDK compatibility as unknown.

Removed

  • puda machine ping. Use puda machine info <machine_ids>.

Upgrading from 0.1.5

The database change is additive: two nullable columns, run.steps and run.notes, are added the first time the CLI opens a project database. Existing rows keep their values; queries using named columns are unaffected (SELECT * returns two more columns).

  1. Stop protocol runs and other database writers.

  2. Back up the database with SQLite's backup API (not a file copy while it's in use):

    import sqlite3
    with sqlite3.connect("puda.db") as src, sqlite3.connect("puda.db.before-0.1.6-rc1") as dst:
        src.backup(dst)
  3. Install v0.1.6-rc1, then from the project root run a query to apply and confirm the migration:

    puda db exec "SELECT name FROM pragma_table_info('run') WHERE name IN ('steps', 'notes')"

    It should return both columns. (puda db schema only prints the bundled schema; it doesn't prove the database was migrated.)

  4. Run puda skills update.

Don't run puda init on an existing project to upgrade it. project.md is unchanged; keep project goals and decisions there, and use puda protocol note for per-run summaries. Old runs have NULL steps and notes, which means "not recorded".

Python SDK 0.0.22 (separate release)

Published separately on PyPI (puda==0.0.22). It wraps telemetry health/stream payloads in {timestamp, data}, so consumers must accept the new envelope before edges are upgraded. This CLI release neither requires nor installs it, and doesn't touch running edges.

Verification

  • Built with GoReleaser from tag v0.1.6-rc1 (commit ead496b); binaries report 0.1.6-rc1. Go tests/vet and all archive checksums passed.
  • puda skills install from this binary installed all seven skills from the v0.1.6-rc1 tag in an isolated home; files matched the tag.
  • Database migration, concurrent notes and a software-only NATS broker test (SDK 0.0.21) passed on the same commit. Hardware, encrypted connections and telemetry consumers were not tested.

v0.1.5

Choose a tag to compare

@zhao-bears zhao-bears released this 22 Oct 12:57

Changelog

🐛 Bug Fixes

  • f82f30f fix(cli): create run before logging lifecycle responses

Released by GoReleaser.

v0.1.4

Choose a tag to compare

@zhao-bears zhao-bears released this 19 Oct 01:24

Fixes

  • Fix puda machine run --run-id <RUN_ID> failing with UNIQUE constraint failed: run.run_id when multiple commands share a run ID and project database logging is enabled.
  • Preserve existing run metadata and command logs when reusing a run ID. Protocol duplicate-ID checks remain unchanged.

Validation

  • All CLI Go tests pass, including regression coverage for run ID reuse across database connections and preservation of existing records.

Released by GoReleaser.

v0.1.3

Choose a tag to compare

@zhao-bears zhao-bears released this 14 Oct 07:29

Breaking Changes

  • puda env is removed. NATS connections are named profiles: puda profile add, list, current, switch, set, and remove.
  • puda config only manages the logged-in user. Server URLs live on the active profile. Project settings are managed with puda project config.
  • A nats_servers value saved in the user config is no longer read. Add it again with puda profile add.

Changes

  • Payload encryption belongs to an encrypted profile (tls:// with --ca and --key). puda encryption status and puda encryption rotate require that profile.
  • A plaintext profile uses nats:// and leaves encryption off.

Released by GoReleaser.

v0.1.3-rc1

v0.1.3-rc1 Pre-release
Pre-release

Choose a tag to compare

@zhao-bears zhao-bears released this 09 Oct 05:42

Breaking Changes

  • puda env is removed. NATS connections are named profiles: puda profile add, list, current, switch, set, and remove.
  • puda config only manages the logged-in user. Server URLs live on the active profile. Project settings are puda project config.
  • A nats_servers value saved in the user config is no longer read. Add it again with puda profile add.

Changes

  • Payload encryption belongs to an encrypted profile (tls:// with --ca and --key). puda encryption status and puda encryption rotate require that profile.
  • A plaintext profile uses nats:// and leaves encryption off.

Released by GoReleaser.

v0.1.2

Choose a tag to compare

@zhao-bears zhao-bears released this 30 Sep 07:06

Breaking Changes

  • Position moved from puda.<machine_id>.tlm.pos to telemetry streams on puda.<machine_id>.tlm.stream.<name>. Update dashboards and loggers subscribed to tlm.pos.
  • puda machine watch takes full NATS subjects as arguments, e.g. puda machine watch 'puda.<machine_id>.tlm.stream.>'. --subjects/-s and --targets are removed; --machines/-m stays.
  • puda machine ping is renamed to puda machine info (ping remains an alias).

Changes

  • puda machine info lists each machine's telemetry streams (tlm_streams) with subject, interval, and description. puda machine list shows tlm_stream_count.
  • puda machine watch subscribes server-side, so it only receives the subjects you ask for. Heartbeats are hidden unless --include-heartbeat is set or a subject names tlm.heartbeat.

Python SDK 0.0.18

  • @tlm_stream(interval=..., name=...) publishes live readings at their own rate, in a worker thread.
  • @machine_state adds driver fields to every MACHINE_STATE update.
  • EdgeRunner publishes the heartbeat and host health (CPU, memory, temperature) on its own; main.py only needs EdgeRunner(nats_client=..., machine_driver=...).

Upgrade guide: https://docs.puda.co/docs/upgrading-to-0.1.x

Full Changelog: v0.1.1...v0.1.2


Released by GoReleaser.

v0.1.1

Choose a tag to compare

@zhao-bears zhao-bears released this 23 Sep 06:49

Changes

  • Machine ping includes host addresses. Edges publish local_ip, tailscale_ip, and magicdns, and puda machine list / puda machine ping show them.
  • puda update hides release candidates unless the version you ask for is itself a pre-release.

Full Changelog: v0.1.0...v0.1.1


Released by GoReleaser.

v0.1.0

Choose a tag to compare

@zhao-bears zhao-bears released this 14 Sep 07:30

Breaking Changes

  • Edge driver methods must be marked @command or they are not advertised or callable. Update the Python SDK to 0.0.17 (puda>=0.0.17).
  • Machine KV is no longer one bucket per machine. Shared MACHINE_STATE and MACHINE_COMMANDS buckets use machine_id as the key.
  • MACHINE_COMMANDS now requires a structured catalog (name, signature, doc, safety). A v0.0.36 edge that only published command text will fail puda machine commands and protocol validate.
  • CLI machine output is JSON by default. Use --human for text (list, ping, state, commands).

Changes

  • Core NATS ping/pong (puda.<id>.cmd.ping and broadcast puda.cmd.ping) with sdk_version, uptime_seconds, run_status, and optional description.
  • puda machine list discovers live edges from pong replies and reports machine_id, description, and registered-only livestream_count. puda machine ping probes specific IDs.
  • puda machine commands lists the live command catalog.
  • @safety on driver commands; protocol run/validate uses the live catalog for confirmation. --yes skips confirmation.
  • wait is a special client-side protocol command (params.seconds); the CLI sleeps locally and does not send it to a machine.
  • puda livestream fleet registry (add, list, attach, detach, rm); HLS/RTSP/RTMP/WebRTC URLs derived from host and stream name.
  • puda healthcheck probes each NATS URL, cluster membership, JetStream, and optional --gateway-servers.
  • Chrony NTP server (infra/chrony) and edge client scripts (infra/chrony/client).
  • JetStream streams declared as JSON config; NATS_PORT and EXTERNAL_PORT; single-node and three-node (R3) NATS layouts.
  • Telemetry throttled: heartbeat at most every 5s, position at most every 3s.
  • Immediate-command default timeout is 10s (was 120s). Missing driver reset is a successful no-op that clears run_id.
  • puda config set user.user_id / user.username after login; puda config edit opens a terminal editor.
  • puda update can install pre-release versions.
  • Protocol validate parses JSON primitive annotations (nested dict/list, typing aliases, unions, Any). Only commands named in the protocol are parsed; unused catalog signatures are ignored. Unannotated parameters, *args, and **kwargs skip the type check.
  • puda-loadgen and test-edge for fleet-scale testing.
  • Python SDK: CommandProcessor extracted from EdgeNatsClient.
  • CLI build/release docs; just publish accepts piped release notes.

Full Changelog: v0.0.36...v0.1.0

v0.1.0-rc4

v0.1.0-rc4 Pre-release
Pre-release

Choose a tag to compare

@zhao-bears zhao-bears released this 14 Sep 03:17

Changes

  • Parse JSON primitive annotations in protocol validate so nested dict/list, typing aliases, unions, and Any catalogs no longer fail
  • Expand test-edge to cover those primitives and safety confirm variants

Released by GoReleaser.