@dypt/cli 0.1.25 → 0.2.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/README.md CHANGED
@@ -37,10 +37,10 @@ dypt auth login
37
37
  dypt auth status
38
38
  ```
39
39
 
40
- By default on macOS, dypt stores CLI credentials in Keychain and falls back to
41
- the URL-scoped file under `~/.config/dypt/tokens` only when Keychain is
42
- unavailable. To deliberately use one file and skip Keychain entirely, set an
43
- absolute path:
40
+ By default on macOS, named accounts store credentials in Keychain. Keychain
41
+ errors fail without a plaintext fallback. Other platforms use restricted
42
+ generation-specific files. To deliberately use isolated single-account file
43
+ mode and skip Keychain entirely, set an absolute path:
44
44
 
45
45
  ```bash
46
46
  DYPT_TOKEN_FILE=/absolute/path/to/dypt-token.json dypt auth login
@@ -53,6 +53,72 @@ with owner-only permissions and tightens an existing regular file before
53
53
  writing. It refuses symlink and non-file destinations. The containing directory
54
54
  and any sandbox access to the file remain the user's responsibility.
55
55
 
56
+ ### Share tasks
57
+
58
+ Sharing commands administer tasks owned by the selected account. Existing
59
+ CLI tokens can share; they do not require another login or scope approval.
60
+ Public links disclose the task and its descendants. Search indexing requests
61
+ are independent of access and do not guarantee discovery or secrecy.
62
+
63
+ ```bash
64
+ dypt --account Work share status 123 --limit 50 --json
65
+ dypt --account Work share publish 123 # preview only
66
+ dypt --account Work share publish 123 --no-index --yes
67
+ dypt --account Work share publish 123 --index --yes
68
+ dypt --account Work share unpublish 123
69
+ dypt --account Work share invite 123 reader --edit # preview only
70
+ dypt --account Work share invite 123 reader --edit --yes
71
+ dypt --account Work share update 123 permission:45 --allow edit-dependencies,edit-notes
72
+ dypt --account Work share remove 123 invite:67
73
+ dypt --account Work share restore 123 permission:45
74
+ ```
75
+
76
+ `publish` and `invite` require `--yes` to mutate and have no hidden prompt.
77
+ Previews include the authenticated account, task, requested change and a
78
+ bounded descendant count ("at least 1000" when capped). They do not reserve
79
+ capacity or bypass fresh server validation. An invitation is **queued**, not
80
+ claimed delivered; delivery failures retain the invitation for worker retry.
81
+
82
+ Invite defaults to `--view`. `--edit` enables all eleven permissions. `--allow`
83
+ replaces the entire set, with unspecified permissions false. Update requires
84
+ exactly one of these modes. Allowed names are `add-subtasks`, `delete-subtasks`,
85
+ `archive-subtasks`, `edit-titles`, `edit-notes`, `edit-priorities`, `edit-statuses`,
86
+ `edit-deadlines`, `edit-order`, `edit-dependencies`, and `edit-tags`.
87
+
88
+ Status separates direct/effective public access, indexing and suspended state,
89
+ and includes the remaining private collaboration capacity. Lists are paged:
90
+ follow `nextCursor` with `--cursor`; a page is not the complete list. Inherited
91
+ access must be managed at its source task. Unpublish removes only a direct
92
+ public grant and reports inherited access that remains. A new public grant
93
+ has indexing off; existing direct grants preserve omitted indexing. Publish
94
+ explicitly reactivates a suspended public grant. Private restore targets only
95
+ suspended direct people/invites, uses current capacity, and does not resend or
96
+ accept an invitation.
97
+
98
+ People can be selected by an exact username/email when unique within the task,
99
+ or by `permission:<id>` / `invite:<id>` from status. Bare numeric target IDs are
100
+ rejected. Ambiguous or over-1,000-entry lookups require a typed handle. Update
101
+ does not edit pending invitations: cancel and reinvite. Historical invitations
102
+ must be removed explicitly before reinviting. Accept incoming invites on the web.
103
+
104
+ Every sharing command supports `--json` and reports authenticated identity.
105
+ Invitation entries show the supplied recipient; only permission entries expose
106
+ usernames.
107
+ Mutation output separates its historical `receipt` from the fresh `current`
108
+ summary. For transport uncertainty, the CLI prints `expectedUserId` and a
109
+ complete retry recipe (`argv`, `env`, `unsetEnv`) using a numeric task ID,
110
+ typed target, original flags and `--idempotency-key`. Confirm the identity and
111
+ execute that exact recipe; do not reconstruct it from renamed tasks/users.
112
+ The human output includes a quoted POSIX command; structured argv/env is
113
+ preferred for other shells. An explicit token-file recipe includes its path,
114
+ never token bytes. No uncertain sharing write is retried automatically.
115
+ Uncertainty output carries the original `idempotencyKey` separately from the
116
+ server's `operationId`. The latter is `null` when no matching operation ID was
117
+ received; reconciliation returns the authoritative receipt.
118
+
119
+ This requires server support for `cli.v1.sharing`. Deploy compatible server
120
+ support before separately publishing/upgrading the CLI.
121
+
56
122
  ### List tasks
57
123
 
58
124
  See tasks from your account:
@@ -248,6 +314,30 @@ creation, inspection, or update commands for the complete structured tag.
248
314
  When tags are merged, the destination tag keeps its name, colour, and
249
315
  description. The source definition is discarded with the source tag.
250
316
 
317
+ Add or remove existing tags on one or more tasks in one atomic mutation:
318
+
319
+ ```bash
320
+ dypt tag assign 123 456 --tag project --tag focus
321
+ dypt tag assign 123 --remove focus
322
+ dypt tag assign 123 456 --remove focus --remove "deep work" --json
323
+ dypt tag assign 123 456 --clear
324
+ ```
325
+
326
+ Choose exactly one mode: repeat `--tag <name>` to add tags, repeat
327
+ `--remove <name>` to remove tags, or use `--clear` to remove every tag.
328
+ Removal keeps all other tags. Removing an existing tag that a selected task
329
+ does not have succeeds and leaves that task's tags unchanged. Names use the
330
+ same case and whitespace normalization as `--tag`; every name must match an
331
+ existing active tag, otherwise the command fails without changing any tasks.
332
+ All selected tasks must pass the existing tag-edit permission and common-owner
333
+ checks. Each mutation accepts at most 500 task references and at most 500
334
+ task/tag combinations.
335
+
336
+ Output follows `tag assign`: human output shows the remaining tags; `--json`
337
+ returns a tag array for one task or an array of tag arrays for multiple tasks,
338
+ in task order. Removal requires a server that accepts `assignMany` mode
339
+ `remove`; deploy that server before upgrading the CLI to use this option.
340
+
251
341
  ## JSON output
252
342
 
253
343
  Most commands support `--json` for agent and automation use.
@@ -383,3 +473,95 @@ candidate notes. Broader searches fail with `CLI_NOTE_SEARCH_TOO_BROAD` and ask
383
473
  you to narrow the query; results are never silently truncated. This is a fixed
384
474
  workload limit, so retrying the same broad query will not help. Candidates
385
475
  subsequently rejected by current permissions also count toward this limit.
476
+
477
+ ### Named-account storage safety
478
+
479
+ Named accounts use a versioned registry under
480
+ `~/.config/dypt/accounts/<sha256(origin)>/registry.json`. The registry contains
481
+ metadata, never bearer tokens. File credentials have separate immutable UUID
482
+ generations, with new directories restricted to 0700 and files to 0600. macOS
483
+ uses generation-specific Keychain items and never silently downgrades an existing
484
+ Keychain account to plaintext. A Keychain failure is actionable, not a reason to
485
+ read a legacy fallback file.
486
+
487
+ Mutations take a short per-origin lock (five-second acquisition timeout).
488
+ An abandoned lock is never stolen based on age. If a timeout names a lock path,
489
+ check that its owner process has stopped before explicitly removing that lock.
490
+ Registry and credential symlinks or nonregular files are rejected. Concurrent
491
+ logout removes only the generation it revoked; a later login survives.
492
+
493
+ ### Upgrading legacy credentials
494
+
495
+ Before first use of the upgraded CLI, stop login/logout and all other credential
496
+ writes from older CLI versions. Keep them stopped until migration cleanup
497
+ finishes. Older binaries ignore the new lock. Fingerprint comparison detects a
498
+ replacement already present, but comparison and deletion are separate operations:
499
+ a legacy write after comparison cannot be protected. There is no automatic
500
+ quiescence guarantee or extra confirmation prompt.
501
+
502
+ Ordinary `https://dypt.app` file credentials and exact-origin macOS Keychain items
503
+ migrate without signing in again, after validating their identity with the server.
504
+ Offline validation leaves legacy bytes untouched. If the server definitively rejects
505
+ a legacy token, `auth login` can obtain fresh approval and retire the rejected
506
+ bytes only after the new validated credential is safely published behind a
507
+ fingerprint cleanup fence. Cleanup-pending metadata blocks
508
+ other authenticated work until cleanup succeeds. Other custom-server legacy
509
+ files have ambiguous origin provenance: they are preserved and require a fresh
510
+ `auth login`; their token is never sent to guess an origin. The unused unscoped
511
+ `cli-token.json` is not imported. Malformed legacy credentials are never guessed or
512
+ deleted automatically: the error identifies the exact file to move to a private
513
+ backup, or the exact Keychain item to preserve and remove in Keychain Access,
514
+ before fresh login. Successful migration deletes the eligible legacy
515
+ credential. Rolling back to an older CLI requires fresh login.
516
+
517
+ ### Selecting named accounts
518
+
519
+ ```bash
520
+ dypt auth login --account personal
521
+ dypt auth login --account work
522
+ dypt auth list --json
523
+ dypt --account work task list --json
524
+ dypt task list --account personal --json
525
+ DYPT_ACCOUNT=work dypt auth status
526
+ dypt auth use personal
527
+ dypt auth logout --account work
528
+ ```
529
+
530
+ Aliases contain 1–64 ASCII letters, digits, dots, underscores or hyphens and are
531
+ matched case insensitively within one canonical server origin. Without an explicit
532
+ login alias, the authenticated username is used when valid, otherwise a stable
533
+ ID digest supplies an alias. Login ignores `DYPT_ACCOUNT` and the default for
534
+ naming. An alias bound to a different user cannot be overwritten; a wrong-user
535
+ approval is revoked on a best-effort basis. Renewing the same user preserves its
536
+ alias unless an explicit unused alias requests a rename.
537
+
538
+ Selection precedence is `--account`, then `DYPT_ACCOUNT`, then the persistent
539
+ default. Conflicting flag occurrences fail. First login becomes default;
540
+ additional logins preserve it. Removing the default clears it and never picks
541
+ another account. Use `auth use` or an explicit selector afterwards. `auth list`
542
+ reads local metadata offline, including storage backend and expiry, without
543
+ reading tokens. `auth status` checks the selected session remotely. Ordinary
544
+ requests reject expired credentials; logout may attempt revocation of an expired
545
+ session. A network failure retains credentials for retry. Definitive authentication
546
+ rejection permits removal of that generation.
547
+
548
+ Each command pins one identity and token through lookup, preview and mutation.
549
+ With multiple accounts, an escaped account notice goes to stderr; task JSON on
550
+ stdout keeps its existing shape. Agents should explicitly select their intended
551
+ account using `--account` or `DYPT_ACCOUNT`, and must not change the shared default
552
+ with `auth use` during a task. This guidance applies to every user.
553
+
554
+ `DYPT_TOKEN_FILE` remains isolated single-account mode with the existing JSON
555
+ format. It has no origin binding: callers must pair it with the intended endpoint.
556
+ It cannot be combined with `--account` or `DYPT_ACCOUNT`, including auth commands.
557
+ Named `auth list/use` are unavailable in this mode. It never changes the registry
558
+ or persistent default. Help, version and local agent instructions do not load or
559
+ migrate credentials. Server overrides accept HTTP(S) origins (including localhost),
560
+ without URL userinfo, API paths, query strings or fragments.
561
+
562
+ ### Maintainer release process
563
+
564
+ CLI releases use Changesets: a reviewed version PR bumps the CLI, and landing it
565
+ publishes to npm. The private application is not published. See the [release runbook](https://github.com/Xexr/dypt/blob/main/docs/runbooks/cli-release.md)
566
+ (repository access required) for checks, npm trusted-publisher setup and recovery.
567
+ Local `cli:publish:check` and `cli:publish:dry-run` require no npm credentials.