Arcane
@thomas/arcanev2026.10.11.1
01README
Management of an Arcane Docker instance through its REST API: GitOps sync setup, compose project lifecycle with a validated deploy for each mode, swarm stack deploy (validated after render, polled until converged), secret/config rotation, and volume/prune cleanup.
02Behaviors
@thomas/arcanev2026.10.11.1arcane.ts
Global Arguments
| Argument | Type | Description |
|---|---|---|
| baseUrl | string | Arcane base URL including port, e.g. https://arcane.example.com:8443. Use https; over http the API key is sent in clear text. |
| apiKey | string | Arcane API key (X-API-Key). Supply via vault: ${{ vault.get(name, key) }} |
| environmentId? | string | Arcane environment id; 0 is the local Docker environment |
| skipTlsVerify? | boolean | Accept self-signed certs (default false: a valid cert is expected) |
| syncs? | array | Desired GitOps sync entries, reconciled by gitops_sync_ensure |
fn version()
Read Arcane's version (GET /version); use it before and after upgrading the manager
fn gitops_repo_list()
List Arcane git repository connections (factory: one `repository` per entry, named `repository:<name>`)
fn gitops_repo_ensure()
Reconcile the git repository connection from globalArgs.repository (create or update). Secrets are sent only when present in the spec.
fn gitops_repo_delete(name: string)
Delete a git repository connection by name. Idempotent: a connection that is already gone counts as deleted.
| Argument | Type | Description |
|---|---|---|
| name | string | Name of the git repository connection to delete |
fn gitops_sync_list()
List Arcane GitOps syncs (factory: one `sync` per entry, named `sync:<name>`)
fn gitops_sync_ensure(prune?: boolean)
Reconcile GitOps syncs from globalArgs.syncs against Arcane (create missing, update drifted). With prune=true, deletes deploy syncs not in the desired list; backup syncs are left alone.
| Argument | Type | Description |
|---|---|---|
| prune? | boolean | Delete existing deploy syncs whose name is not in globalArgs.syncs (destructive). Backup syncs are never pruned. |
fn gitops_sync_trigger(names?: array)
Run the named syncs (fan-out): git pull, and a redeploy when the content changed. Empty `names` triggers every deploy sync; a backup sync runs only when named. Waits for each sync to finish; records every result, then throws if Arcane reported any sync failed or already in progress.
| Argument | Type | Description |
|---|---|---|
| names? | array | Sync names to trigger; empty means every deploy sync (a backup sync runs only when named) |
fn gitops_sync_status(names?: array)
Read last/next run state for the named syncs (fan-out: one `sync-status` per sync, named `sync-status:<name>`). Empty `names` checks all syncs. Surfaces lastSyncStatus/lastSyncError/lastSyncCommit, the missing gitops health view.
| Argument | Type | Description |
|---|---|---|
| names? | array | Sync names to check; empty means all |
fn project_list()
List Arcane compose projects (factory: one `project` per entry, named `project:<name>`)
fn project_validate(target?: string, composePath?: string, composeContent?: string, envPath?: string, envContent?: string)
Validate compose content LOCALLY with `docker compose config` (fail-closed and read-only: no Arcane mutation). Takes composePath/envPath or inline composeContent/envContent.
| Argument | Type | Description |
|---|---|---|
| target? | string | Label for the result (defaults to composePath or 'inline') |
| composePath? | string | Path to a local compose file |
| composeContent? | string | Inline compose content (instead of composePath). Not sensitive: put secrets in envContent and reference them as ${VAR} |
| envPath? | string | Path to a local .env file |
| envContent? | string | Inline .env content (instead of envPath); may carry secrets, so it is marked sensitive |
fn project_get(name: string)
Read a compose project's full detail (compose + env content, status, gitOps mode) into a `project-detail` resource. Used for rollback snapshots.
| Argument | Type | Description |
|---|---|---|
| name | string | Project name |
fn project_create(name: string, composePath?: string, composeContent?: string, envPath?: string, envContent?: string)
Create a compose project in Arcane (direct mode), pushing compose content via the API. Validates locally first and stops if validation fails or cannot run.
| Argument | Type | Description |
|---|---|---|
| name | string | Project name |
| composePath? | string | |
| composeContent? | string | |
| envPath? | string | |
| envContent? | string |
fn project_update(name: string, composePath?: string, composeContent?: string, envPath?: string, envContent?: string)
Update a compose project's content in Arcane (direct mode). Validates locally first and stops if validation fails or cannot run. Does NOT redeploy; use project_redeploy or project_deploy.
| Argument | Type | Description |
|---|---|---|
| name | string | Project name |
| composePath? | string | |
| composeContent? | string | |
| envPath? | string | |
| envContent? | string |
fn project_deploy(name: string, composePath?: string, composeContent?: string, envPath?: string, envContent?: string, rollback?: boolean, healthTimeoutSec?: number, pollIntervalSec?: number)
Validated, mode-aware deploy of a compose project. Snapshots prior state, applies, polls health, and rolls back by default on failure.
| Argument | Type | Description |
|---|---|---|
| name | string | Project name |
| composePath? | string | Direct mode: new compose file to deploy |
| composeContent? | string | Direct mode: inline compose content. Not sensitive: put secrets in envContent and reference them as ${VAR} |
| envPath? | string | |
| envContent? | string | |
| rollback? | boolean | Roll back to prior state on failure (direct mode). false = stop and report, leaving the failed state for inspection. |
| healthTimeoutSec? | number | How long the redeploy and the wait for the project to become healthy may take together. A rollback gets the same time again. |
| pollIntervalSec? | number |
fn swarm_service_list()
List swarm services (factory: one `swarm-service` per entry, named `swarm-service:<name>`)
fn swarm_service_get(name: string)
Get a single swarm service by name
| Argument | Type | Description |
|---|---|---|
| name | string |
fn swarm_service_rollback(name: string)
Roll a swarm service back to its previous spec (Arcane POST .../rollback)
| Argument | Type | Description |
|---|---|---|
| name | string |
fn swarm_service_force_update(name: string, convergeTimeoutSec?: number, pollIntervalSec?: number)
Force-redeploy a swarm service via Arcane (bumps spec.TaskTemplate.ForceUpdate + PUT), which recreates its tasks without changing config. Useful after a dependency (e.g. its DB) becomes ready post-deploy. Polls convergence; throws if it does not converge.
| Argument | Type | Description |
|---|---|---|
| name | string | Swarm service name (e.g. unifi_unifi) |
| convergeTimeoutSec? | number | |
| pollIntervalSec? | number |
fn swarm_stack_list()
List swarm stacks (factory: one `swarm-stack` per entry, named `swarm-stack:<name>`)
fn swarm_stack_get(name: string)
Get a single swarm stack by name
| Argument | Type | Description |
|---|---|---|
| name | string |
fn swarm_stack_validate(name: string, composePath?: string, composeContent?: string, envPath?: string, envContent?: string)
Validate a swarm stack via Arcane's config render (POST /swarm/stacks/config/render).
| Argument | Type | Description |
|---|---|---|
| name | string | Stack name |
| composePath? | string | |
| composeContent? | string | |
| envPath? | string | |
| envContent? | string |
fn swarm_stack_deploy(name: string, composePath?: string, composeContent?: string, envPath?: string, envContent?: string, prune?: boolean, convergeTimeoutSec?: number, pollIntervalSec?: number)
Validated deploy of a swarm stack: render (any render error stops the deploy) -> POST the stack -> poll service convergence.
| Argument | Type | Description |
|---|---|---|
| name | string | Stack name |
| composePath? | string | |
| composeContent? | string | |
| envPath? | string | |
| envContent? | string | |
| prune? | boolean | Remove services no longer present in the compose file |
| convergeTimeoutSec? | number | |
| pollIntervalSec? | number |
fn swarm_stack_remove(name: string, removeTimeoutSec?: number, pollIntervalSec?: number)
Remove a swarm stack by name (docker stack rm via Arcane) and confirm the stored record is cleared.
| Argument | Type | Description |
|---|---|---|
| name | string | |
| removeTimeoutSec? | number | Max seconds to keep re-issuing DELETE until the stack record 404s |
| pollIntervalSec? | number |
fn swarm_stack_tasks(name: string, onlyProblems?: boolean)
List a swarm stack's tasks (factory: one `swarm-task` per task, named `swarm-task:<task id>`) with per-task currentState + error: the deploy debug view that surfaces rejected/failed reasons (missing bind path, non-zero exit, placement).
| Argument | Type | Description |
|---|---|---|
| name | string | Stack name |
| onlyProblems? | boolean | Emit only tasks whose currentState is rejected/failed/orphaned (the error-bearing ones) |
fn volume_list()
List docker volumes (factory: one `volume` per entry, named `volume:<name>`). Includes `inUse` so orphaned volumes are visible.
fn volume_remove(name: string)
Remove a docker volume by name. Idempotent: a volume that is already gone counts as removed. An in-use volume is refused and left in place; stop or remove the containers using it first.
| Argument | Type | Description |
|---|---|---|
| name | string |
fn volume_prune()
Prune UNUSED anonymous docker volumes (Docker default: named volumes are NOT removed). Removes only volumes no container references. For a specific named volume use volume_remove.
fn network_prune()
Prune unused docker networks (no attached containers). Safe: only removes networks nothing is using.
fn image_prune(dangling?: boolean)
Prune unused images. dangling:true (default) removes only dangling layers; dangling:false removes ALL images not referenced by a container.
| Argument | Type | Description |
|---|---|---|
| dangling? | boolean | true = only dangling layers (safe); false = all unused images |
Resources
repository(infinite)— An Arcane git repository connection
sync(infinite)— An Arcane GitOps sync entry (one project pulled from git)
sync-status(infinite)— A GitOps sync's last/next run state (lastSyncStatus/lastSyncError/lastSyncCommit): the gitops health view
arcane-version(infinite)— Arcane's reported version (current + newest available), for checks before and after an upgrade
project(infinite)— An Arcane compose project
operation-result(infinite)— Result of a mutating Arcane operation (sync trigger, project lifecycle)
project-detail(infinite)— A compose project's full detail incl. compose/env content (rollback snapshot)
validation(infinite)— Result of a local compose validation (`docker compose config`)
swarm-secret(infinite)— A swarm secret (immutable; rotate via secret_rotate)
swarm-config(infinite)— A swarm config (immutable; rotate via config_rotate)
swarm-service(infinite)— A swarm service summary
swarm-stack(infinite)— A swarm stack (a deployed compose stack)
swarm-stack-render(infinite)— Result of Arcane's swarm-stack config render: the mandatory pre-deploy validation gate
swarm-task(infinite)— A swarm task (a replica placement attempt) with state + error: the deploy debug view
volume(infinite)— A docker volume (incl. inUse, for spotting orphans)
prune-result(infinite)— Result of a docker prune (space reclaimed + deleted items)
03Previous Versions
2026.06.24.1
Removed 1 behaviors
2026.05.24.1
Repairs the broken 2026.05.23.1 release, which shipped a version bump without its matching upgrades[] migration entry and left the @thomas/arcane type unloadable ("Last upgrade toVersion 2026.05.22.1 does not match model version 2026.05.23.1"). Adds the no-op migrations for .23.1 and .24.1; globalArguments schema is unchanged. .23.1 is yanked in favour of this version.
2026.05.23.1yanked
2026.05.22.1
04Stats
A
93 / 100
Downloads
32
Archive size
66.3 KB
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types (deprecated)1/1earned
- Dependencies pass trust audit2/2earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License1/2partial
no SPDX license declared
- Verified public repository2/2earned
05Platforms
06Labels