@safetech/inheriti-cli 0.0.22-dev.0 → 0.0.24-dev.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/main.js +5167 -4857
- package/dist/main.js.map +4 -4
- package/package.json +1 -1
- package/skill/inheriti-cli/SKILL.md +1 -1
- package/skill/inheriti-cli/references/automation-providers.md +55 -2
- package/skill/inheriti-cli/references/automations.md +3 -1
- package/skill/inheriti-cli/references/github-workflow.md +44 -0
- package/skill/inheriti-cli/references/identity-and-discovery.md +1 -1
- package/skill/inheriti-cli/references/plans-create-and-inspect.md +1 -1
- package/skill/manifest.json +1 -1
package/package.json
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
name: inheriti-cli
|
|
3
3
|
description: Use the Inheriti® CLI to find, create, inspect, reveal, download, or use protected plans and to configure Business automations from a user's natural-language request.
|
|
4
4
|
metadata:
|
|
5
|
-
version: 0.0.
|
|
5
|
+
version: 0.0.24-dev.0
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# Inheriti® CLI
|
|
@@ -4,9 +4,62 @@ Read only the section for the workload that will actually execute the protected
|
|
|
4
4
|
|
|
5
5
|
## GitHub Actions
|
|
6
6
|
|
|
7
|
-
Identify the intended repository, environment, workflow file, and ref before binding `automations create --provider GITHUB` to the exact `--repository OWNER/REPO`,
|
|
7
|
+
Identify the intended repository, GitHub job environment, workflow file, and ref before binding `automations create --provider GITHUB` to the exact `--repository OWNER/REPO`, `--environment NAME`, and `--workflow OWNER/REPO/.github/workflows/FILE.yml@refs/heads/BRANCH`. Keep the Business deployment (`local`/`dev`), connection deployment-environment, and GitHub environment distinct; do not infer one from another. The CLI does not create a repository or initial pairing job.
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
### Resolve missing context
|
|
10
|
+
|
|
11
|
+
Inspect safe repository/workflow metadata first. If the user points to a local project, first identify its git root, remote names and safe repository identity, branch and status; inspect the selected app's manifests, lockfiles, scripts, Dockerfile, source/schema references to required environment variable **names**, and existing `.github/workflows` files. For a monorepo, identify the app that consumes the protected values and its actual command. Read files as data; do not run package scripts during discovery, read `.env` or secrets, or print credential-bearing remote URLs or workflow values. The current directory or sole checkout is not necessarily the intended project. `gh workflow list --repo OWNER/REPO` can show candidates in the selected repository; confirm the intended environment and ref separately. Follow the [GitHub project inspection and pairing workflow guide](github-workflow.md) for the concrete inspection and initial job.
|
|
12
|
+
|
|
13
|
+
Ask only questions not already answered by Business, the user, or verified metadata:
|
|
14
|
+
|
|
15
|
+
- “Which repository and workflow/job needs access to this plan?” Present discovered candidates when available.
|
|
16
|
+
- “Which GitHub environment and branch should be allowed?” Explain that these identify the trusted workload, rather than choosing `production` or `main` by default.
|
|
17
|
+
- “Which plan fields does that job need, and which variable names does the application expect?” Resolve field selectors from safe plan metadata; never ask for their values.
|
|
18
|
+
- “Should this run manually, on a schedule, or as part of the existing deployment?” Ask only when a trigger or execution step must be added; preserve an existing trigger unless a change is requested.
|
|
19
|
+
- Ask for the responsible member only when absent or rejected by Business. Do not ask again for a supplied plan or connection.
|
|
20
|
+
|
|
21
|
+
### First connection and pairing
|
|
22
|
+
|
|
23
|
+
1. Inspect existing connections and plan grants as described in [automations](automations.md). For a new connection, preview the exact repository/environment/workflow/ref and create it only within the requested scope. Retain the returned connection ID and expected audience as non-secret setup metadata.
|
|
24
|
+
2. Prepare a pairing job in that exact workflow file/ref, with the configured job `environment`, `id-token: write`, and an installed CLI targeting the same Business deployment. Use the [initial pairing workflow template](github-workflow.md#initial-pairing-workflow) and a verified published CLI version; do not guess a package version or fall back to another deployment when unavailable. In an existing workflow, gate pairing behind an explicit manual input that defaults off; normal push or deployment runs must not redeem again. A request to prepare the workflow authorizes a reversible local draft and its review, so make it without asking again. Keep unresolved placeholders in a clearly marked proposal outside active `.github/workflows` and resolve them before saving an executable workflow. Commit, push, dispatch, and deployment each require authorization covering that action.
|
|
25
|
+
3. The job's run step redeems identity directly from GitHub Actions. Set these non-secret job variables from the selected connection and use the existing CLI command:
|
|
26
|
+
|
|
27
|
+
```sh
|
|
28
|
+
# Inside the configured GitHub Actions job, after installing the matching CLI.
|
|
29
|
+
export INHERITI_AUTOMATION_CONNECTION_ID="<connection-id>"
|
|
30
|
+
export INHERITI_AUTOMATION_AUDIENCE="<expected-audience-returned-by-cli>"
|
|
31
|
+
inheriti automations pair redeem
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Never retrieve an OIDC token for the agent or paste one into `automations verify`. Running `pair redeem` in the operator's local terminal does not prove the GitHub workload identity.
|
|
35
|
+
4. Once the job is ready to execute, inspect the full effect of its manual dispatch on all jobs, then run `inheriti automations pair start --connection CONNECTION_ID` on the operator side and execute the approved pairing job within the returned ten-minute window. `pair start` returns after opening the window; its “Waiting” message is not confirmation of verification. If a push or dispatch is still awaiting authorization, report that prerequisite rather than repeatedly opening windows.
|
|
36
|
+
5. Inspect the connection for `VERIFIED`. Only then create and activate the chosen plan grant with the selected responsible member, subject to Business permissions and CLI approvals. Do not claim that successful pairing also activated a plan grant.
|
|
37
|
+
|
|
38
|
+
### Generate and integrate the actual workload
|
|
39
|
+
|
|
40
|
+
After verification and an active grant:
|
|
41
|
+
|
|
42
|
+
```sh
|
|
43
|
+
inheriti automations usage --plan PLAN_ID --connection CONNECTION_ID --field ASSET.FIELD
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
This emits YAML pinned to a Business-verified Action and CLI release; it refuses when that release is unavailable. Follow its printed repository/path/branch. It is a starting example with a manual trigger and a non-empty-value check, not the user's deployment command. Preview how the selected field maps to the application's variable and how the real consuming command runs through the Action's protected execution; do not introduce an `echo`, output, artifact, or chat-visible secret check. This command accepts one `--field`; do not invent repeatable flags for additional mappings. Inspect the generated Action contract before adapting it.
|
|
47
|
+
|
|
48
|
+
If the workflow already exists, merge the required job or steps without replacing existing jobs, triggers, permissions, environment protections, or deployment logic. Check effective job permissions: an existing job-level permissions block must still allow the required OIDC permission. Changing the job environment, file/ref, or repository can invalidate trust; inspect the connection before proposing a trust change, and reverify when required. Remove only pairing scaffolding introduced for this setup when it is no longer needed and its removal is in scope.
|
|
49
|
+
|
|
50
|
+
Execute only the authorized run and inspect its safe status plus plan/member logs. Report connection verification, grant activation, workflow preparation, and actual execution separately. Generated YAML, a successful pairing run, or a passing example value check does not prove the user's application deployment succeeded.
|
|
51
|
+
|
|
52
|
+
### Reuse example
|
|
53
|
+
|
|
54
|
+
User: “Use the Enterprise Safe plan in the existing deploy job in acme/payments. Business supplied connection C and member M.” Inspect C's GitHub trust and the plan grant. If its repository, environment, and workflow/ref match and C is verified, retain C, skip connection creation and pairing, and reuse an active matching grant. If the grant is missing, preview creating/activating it for M; do not silently replace a grant's responsible member. Inspect the deploy job, resolve only missing field mappings, generate usage with C explicitly, and preview the smallest workflow diff. If the actual job differs from C's trust, explain the mismatch and ask which target is intended instead of silently rebinding C.
|
|
55
|
+
|
|
56
|
+
### Pairing and run recovery
|
|
57
|
+
|
|
58
|
+
- Expired pairing window: inspect connection status and the specific run first. If still unverified and the same workload is intended, open one fresh window when the job can run and obtain fresh proof through `pair redeem`; never reuse a token or create a replacement connection merely for expiry.
|
|
59
|
+
- Identity/audience mismatch: compare the configured repository, job environment, workflow/ref, and expected audience with safe metadata from that run. Correct the selected setup or ask about conflicting intent; do not broaden trust or remove environment protections to pass verification.
|
|
60
|
+
- Missing `id-token: write`, CLI installation, GitHub access, or environment approval: identify that prerequisite and who must act. An environment waiting for approval is pending, not a pairing failure. Retry only after the prerequisite is resolved; refresh an expired window then.
|
|
61
|
+
- Run timeout or missing completion: inspect the returned run ID before dispatching another run. Report pending or unconfirmed when appropriate. Do not rerun a deployment just to check whether it succeeded.
|
|
62
|
+
- Inactive/rejected grant or unavailable verified release: stop at that gate and report the safe reason. Do not switch account, member, deployment, or package version silently.
|
|
10
63
|
|
|
11
64
|
## Google Cloud Run service or job
|
|
12
65
|
|
|
@@ -10,7 +10,9 @@ Inspect existing connections and grants before proposing changes. If Business su
|
|
|
10
10
|
|
|
11
11
|
The order is: existing workload and CLI runtime → connection (`automations create`) → identity pairing or verification (`automations pair ...` or `automations verify`) → plan grant (`automations grant create`, then `activate`) → mapping and runtime setup (`automations setup` or `automations usage`) → run and inspect safe plan/member logs. `automations trust` changes the non-secret identity policy and may require reverification; `automations disable` stops a connection. `automations grant member` changes its responsible member; `revoke` ends a grant. Present the exact connection, plan, member, and effect before these changes. Never pass a workload proof, private key, or credential as an argument or through chat.
|
|
12
12
|
|
|
13
|
-
`automations pair start [--connection ID]` opens a ten-minute window; `pair redeem` runs inside the configured workload and sends a fresh native proof directly to Business. Provider helpers can pair a temporary ECS task, Cloud Run job, or SSM-managed EC2 instance after target/revision inspection and confirmation. `automations verify` opens a native proof-entry window only when there is already a secure transfer route; it does not fetch proof from Cloud Run or ECS. Review the provider-specific route in [provider workflows](automation-providers.md).
|
|
13
|
+
`automations pair start [--connection ID]` opens a ten-minute window; `pair redeem` runs inside the configured workload and sends a fresh native proof directly to Business. Provider helpers can pair a temporary ECS task, Cloud Run job, or SSM-managed EC2 instance after target/revision inspection and confirmation. `automations verify` opens a native proof-entry window only when there is already a secure transfer route; it does not fetch proof from Cloud Run or ECS. Review the provider-specific route in [provider workflows](automation-providers.md); for GitHub, read its first-pairing, existing-workflow, reuse, and recovery guidance before preparing a job.
|
|
14
|
+
|
|
15
|
+
For a verified workload, pass non-secret operation context before the child separator: `inheriti secrets exec PLAN_ID --automation --env TOKEN=asset.field --reason 'Deploy service' --target service-name --version 1.2.3 -- command`. Optional flags are `--reason`, `--commit`, `--workflow`, `--pipeline`, `--target`, `--image`, and `--version`; repeat none. GitHub Actions automatically supplies the commit, workflow, and run URL from its allowlisted environment when present; flags override those values. Launchers may set `INHERITI_AUTOMATION_REASON`, `INHERITI_AUTOMATION_TARGET`, `INHERITI_AUTOMATION_IMAGE`, and `INHERITI_AUTOMATION_VERSION`. Do not put secrets or arbitrary child arguments in context. This requires a CLI built against a Client SDK release carrying operation context; do not package against the older published SDK.
|
|
14
16
|
|
|
15
17
|
`automations setup --plan PLAN_ID --connection CONNECTION_ID ...` maps plan fields to runtime inputs. Select each needed `ASSET.FIELD` with repeatable `--only` and use `--map NAME=ASSET.FIELD` for an application variable; inspect the complete mapping before action. Use `--map-all` only when the user explicitly wants every eligible field. It can print or save a launcher for a custom/container runner, preview a managed ECS/Cloud Run change, or prepare an EC2 launcher and systemd unit. Cloud changes require an explicit `--apply` with a prepared image and reviewed target revision; EC2 writes require `--install` and confirmation. The CLI does not invent or create an app, repository, workload, IAM role, or cloud account. `automations usage` generates a GitHub workflow only for a verified connection, active grant, and Business-verified Action/CLI release.
|
|
16
18
|
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
# GitHub project inspection and pairing workflow
|
|
2
|
+
|
|
3
|
+
Use this only for a selected GitHub Actions automation. Keep the selected Business deployment, GitHub repository, workflow file/ref, and job environment explicit throughout inspection, connection creation, pairing, and protected execution.
|
|
4
|
+
|
|
5
|
+
## Inspect the selected project
|
|
6
|
+
|
|
7
|
+
1. Confirm which local checkout the user means. Read its git root, current branch and status, remote **names**, and a sanitized repository identity. Do not print raw remote URLs: they can contain credentials. Compare the identity with the GitHub repository the user selected; do not infer intent from the current directory or a single checkout.
|
|
8
|
+
2. For the selected app, inspect package manifests, lockfiles, declared scripts and runtime engines, Dockerfile or deployment configuration, and `.github/workflows` files. In a monorepo, trace the actual app path and working directory. Inspect text without executing package scripts. Never read `.env` files, credential stores, secret values, workflow logs containing values, or full unfiltered provider metadata.
|
|
9
|
+
3. Trace the command that will consume protected values and the required environment variable **names** from source, schema, or safe documentation. Compare these with safe plan field selectors and the existing workflow's trigger, environment, permissions, install steps, and run command. Ask only for technical choices still unresolved, such as a target workflow, environment, mapping, or command when no reliable source establishes it.
|
|
10
|
+
|
|
11
|
+
## Initial pairing workflow
|
|
12
|
+
|
|
13
|
+
This is a complete pairing-only workflow shape for a **new** file. A request to prepare it authorizes a reversible local draft; make and review that draft without asking again. Keep unresolved placeholders in a clearly marked proposal outside active `.github/workflows`. Resolve every angle-bracket placeholder from inspected, non-secret metadata before saving an executable workflow there. The selected workflow path and branch must exactly match the connection trust; its job environment must match the trusted GitHub environment. Use the same CLI package and deployment verified for this Business instance. Inspect the selected CLI package's `engines.node`, then choose a compatible Node version; do not guess either version. If the project already has a compatible Node setup, reuse it. Otherwise use a reviewed, pinned `actions/setup-node` commit SHA; resolve the placeholder to that exact SHA before writing. Choose a runner that can reach the selected Business deployment.
|
|
14
|
+
|
|
15
|
+
```yaml
|
|
16
|
+
name: Pair Inheriti automation identity
|
|
17
|
+
on:
|
|
18
|
+
workflow_dispatch:
|
|
19
|
+
permissions:
|
|
20
|
+
id-token: write
|
|
21
|
+
jobs:
|
|
22
|
+
pair-inheriti:
|
|
23
|
+
runs-on: <selected-runner>
|
|
24
|
+
environment: <selected-github-environment>
|
|
25
|
+
steps:
|
|
26
|
+
- uses: actions/setup-node@<reviewed-setup-node-commit-sha>
|
|
27
|
+
with:
|
|
28
|
+
node-version: '<node-version-compatible-with-verified-cli-engines.node>'
|
|
29
|
+
- name: Install verified Inheriti CLI
|
|
30
|
+
run: npm install --global --engine-strict '@safetech/inheriti-cli@<exact-verified-published-version>'
|
|
31
|
+
- name: Redeem GitHub workload identity
|
|
32
|
+
env:
|
|
33
|
+
INHERITI_AUTOMATION_CONNECTION_ID: <selected-connection-id>
|
|
34
|
+
INHERITI_AUTOMATION_AUDIENCE: <expected-audience-returned-by-cli>
|
|
35
|
+
run: inheriti automations pair redeem
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
The connection ID and audience are setup metadata, not credentials. Never put an OIDC token, plan value, identity proof, or secret in YAML, command arguments, chat, logs, or outputs. The CLI install must use the verified release for the chosen deployment; if no published verified release is available, stop and report that gate. For local Business, the hosted runner cannot normally reach `localhost`, and there is no verified local GitHub release manifest; do not substitute a dev release or bypass deployment locks through API environment overrides.
|
|
39
|
+
|
|
40
|
+
For an **existing** workflow, prefer a separate pairing job gated by an explicit manual input that defaults off. Never add an unconditional `pair redeem` step to a push, schedule, or normal deployment job: it would rerun after the pairing window is consumed. For example, add `workflow_dispatch.inputs.pair_inheriti` as a boolean with `default: false`, then gate the pairing job with `if: github.event_name == 'workflow_dispatch' && inputs.pair_inheriti`. The corresponding approved dispatch is `gh workflow run FILE --repo OWNER/REPO --ref BRANCH -f pair_inheriti=true`. Preserve all existing triggers and jobs. If the workflow has no `workflow_dispatch`, add it only after checking what its other jobs would do during manual dispatch. If a separate job is impossible, gate each pairing-only step with the same condition and verify the existing job's effective `id-token: write` permission. Keep unrelated environment protections and permissions. Reuse a compatible existing CLI and Node setup only after verifying its version, engine, and Business endpoint. Prepare and review the local diff when requested; show unresolved choices as a proposal outside active workflows until they are resolved.
|
|
41
|
+
|
|
42
|
+
The workflow must exist on the repository's default branch for GitHub's manual `workflow_dispatch` entry point. Confirm that prerequisite and the selected ref; `gh workflow run FILE --repo OWNER/REPO --ref BRANCH` selects the ref to run after the workflow is available. For an existing combined workflow, use the matching `-f pair_inheriti=true` input shown above. Inspect the full effect of that dispatch on every job before running it; pairing must not unintentionally trigger deployment or other side effects. See [GitHub's manual-run documentation](https://docs.github.com/en/actions/how-tos/manage-workflow-runs/manually-run-a-workflow) and [`gh workflow run`](https://cli.github.com/manual/gh_workflow_run). Commit, push, environment approval, and dispatch need authorization for those actions. Start the ten-minute `inheriti automations pair start --connection CONNECTION_ID` window only when the approved job is ready to execute. Record the run ID, inspect its safe status and the connection's verification state, and poll when pending; do not treat a dispatch or “Waiting” message as proof. Create or activate a plan grant only after the connection is `VERIFIED`.
|
|
43
|
+
|
|
44
|
+
After pairing, remove only temporary pairing scaffolding introduced for this setup when transitioning to the real workload, unless a gated pairing-only recovery job is intentionally retained. `inheriti automations usage --plan PLAN_ID --connection CONNECTION_ID --field ASSET.FIELD` generates a one-field, non-empty-value smoke test. Inspect the generated Action's supported inputs, then map every required plan field through its `env` input and run the selected application's real consuming command through its protected `run` execution. Prepare that job's own checkout, compatible runtime and dependency installation from the inspected project; setup in the separate pairing job does not carry over. Give checkout `contents: read` alongside the required OIDC permission, and resolve added Action references to reviewed versions before making the proposal executable. Preserve the existing workflow's trigger and deployment behavior. Preview the mapping and target changes before writing or running; never print a protected value to prove it works.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Identity and discovery
|
|
2
2
|
|
|
3
|
-
Run `inheriti help` or `inheriti help COMMAND SUBCOMMAND` before using an unfamiliar command; `inheriti version` reports the installed build. `inheriti update` checks its channel, while `inheriti update --install` installs an offered build after confirmation. A required Business CLI update is checked after login and before authenticated commands.
|
|
3
|
+
Run `inheriti help` or `inheriti help COMMAND SUBCOMMAND` before using an unfamiliar command; `inheriti version` reports the installed build. `inheriti update` checks its channel, while `inheriti update --install` installs an offered build after confirmation. A required Business CLI update is checked after login and before authenticated commands. Run `inheriti skill install` in a terminal to choose Codex, Claude Code, both, or another skills folder. In scripts, specify `--target codex|claude|all` or `--directory ABSOLUTE_PATH`; a pipe never chooses an agent. The CLI remembers a successful choice and reconciles that skill on later commands and upgrades. A running agent may need a new session to load updated instructions. `inheriti setup` configures shell autocomplete, and `inheriti completion bash|zsh|fish` prints a completion script; neither is needed to install this skill.
|
|
4
4
|
|
|
5
5
|
`inheriti login` opens a browser and needs an interactive terminal. `inheriti logout` clears the local operator session, not plans. In Business, run `inheriti organizations list` to see eligible Organisations and the selected one; use `inheriti organizations use [ID]` to select. If more than one Organisation could contain the requested plan, establish the right one before searching or changing anything. The CLI and server enforce membership and permissions.
|
|
6
6
|
|
|
@@ -2,6 +2,6 @@
|
|
|
2
2
|
|
|
3
3
|
`inheriti plans create [--title NAME] [--description TEXT] [--asset TYPE ...]` passes **editable, non-secret hints** to the local plan assistant. Preserve title and description supplied in the user's request; use exact catalog IDs from `inheriti help plans create` for asset hints (for example, `--asset API-KEY`, not `--asset "API key"`). Do not put a password, recovery phrase, private key, token, or protected file contents in these options or in plan metadata. If the request already contains a secret-like value, do not repeat it or ask for another value in chat; tell the person to enter it only in the secure window.
|
|
4
4
|
|
|
5
|
-
Creation requires sign-in, a selected Inheriti Business Organisation, an interactive terminal, a desktop window, and a claimed Organisation Key for that member. On first use, the CLI may offer to download its local assistant runtime and model (about 1.1 GB). The person enters protected content in the secure window, edits the draft, confirms creation, and may need to release the Organisation Key in SafeKey Mobile. Let the CLI present its progress. Report the plan ID and status returned by the CLI; do not claim completion while it is pending.
|
|
5
|
+
Creation requires sign-in, a selected Inheriti Business Organisation, an interactive terminal, a desktop window, and a claimed Organisation Key for that member. On first use, the CLI may offer to download its local assistant runtime and model (about 1.1 GB). The person enters protected content in the secure window, edits the draft, confirms creation, and may need to release the Organisation Key in SafeKey Mobile. Let the CLI present its progress. After the result appears, the person selects Continue or closes the window to return to the terminal. Report the plan ID and status returned by the CLI; do not claim completion while it is pending.
|
|
6
6
|
|
|
7
7
|
`inheriti plans list` finds safe plan metadata, `inheriti plans show PLAN_ID` shows assets, fields, participants and policy, and `inheriti plans logs PLAN_ID` shows activity. Use these for verification and context, not as sources of protected values. For a request such as “create a plan called Family Archive with description Documents for my brother,” run the create command with those two hints, then hand off to the secure window. If the user requests an unsupported asset or omits important non-secret structure, explain the available choices rather than inventing one.
|
package/skill/manifest.json
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"schema":1,"cliVersion":"0.0.
|
|
1
|
+
{"schema":1,"cliVersion":"0.0.24-dev.0","deployment":"dev","sha256":"93640536153d25762ea551cc03df930cb60f5d23da280b719e7e633886db8628"}
|