workspace, examples/artifacts, docs: add artifacts share shorthand

Handing someone a clone link still took two steps and a manual URL
assembly: mint a read token with token create, then splice the token
into the repo's remote by hand. Add a top-level `artifacts share`
that does both and prints just the credentialed remote URL on
stdout, one clone/push-ready string with no JSON envelope.

Scope defaults to read, the common case for a fetch-only link; pass
--scope write for a pushable URL. --ttl takes the same duration
grammar as create. The repo must already exist, so a missing repo
fails before any token is minted. It is the read-side counterpart to
create: where create sets up a repo and a push remote, share hands
out a URL to clone from.

Collapse the example's token-create-plus-hand-built-URL onto the new
command and document the shorthand.

Author: aron-cf

docs/15_artifacts_interface.md

@@ -69,13 +69,14 @@ argv-driven CLI backed by one implementation, so they cannot drift.
   Every flag-shape decision lives in `artifacts/cli.ts`; the typed
   methods and the CLI route to the same client.
 
-The one exception is the CLI's top-level `create` shorthand, which
-composes `create` and `createToken` and then registers a git remote.
-The composition and the git step are CLI-only: there is no single
-typed method for them, and the git step rides on an injected seam
-(below) rather than a client method. The pieces it composes are still
-the same client methods, so the two doors do not drift on the parts
-they share.
+The exceptions are the CLI's top-level shorthands. `create` composes
+`create` and `createToken` and then registers a git remote; `share`
+composes `get` and `createToken` and prints a single credentialed
+URL. These compositions are CLI-only — there is no single typed
+method for them, and `create`'s git step rides on an injected seam
+(below) rather than a client method. The pieces they compose are
+still the same client methods, so the two doors do not drift on the
+parts they share.
 
 ## Typed surface
 
@@ -115,8 +116,8 @@ result type carries a page of tokens plus a `total`. So
 
 ## CLI surface
 
-`artifacts.cli({ argv })` dispatches a top-level `create` shorthand
-plus two groups, `repo` and `token`.
+`artifacts.cli({ argv })` dispatches two top-level shorthands,
+`create` and `share`, plus two groups, `repo` and `token`.
 
 ```
 artifacts help                       # top-level help
@@ -126,6 +127,7 @@ artifacts token --help               # token group help
 
 artifacts create <name> [--scope read|write] [--ttl DUR] [--remote NAME] \
                         [--default-branch B] [--description D] [--force]
+artifacts share <name> [--scope read|write] [--ttl DUR]
 
 artifacts repo create <name> [--description D] [--default-branch B] [--read-only]
 artifacts repo get <name>
@@ -141,8 +143,9 @@ artifacts token delete <repo> <id|plaintext>   # alias: revoke
 
 Output is machine-first. Reads and data-producing mutations
 (`create`, `repo create`, `get`, `list`, `import`,
-`token create/list/get`) print JSON on stdout. `delete` and
-`token delete` print a one-line confirmation.
+`token create/list/get`) print JSON on stdout. `share` prints a
+single credentialed remote URL. `delete` and `token delete` print a
+one-line confirmation.
 
 ### The `create` shorthand
 
@@ -185,6 +188,24 @@ same `workspace.git.cli(...)` the built-in `git` command uses. The
 typed `create`/`createToken` methods never learn about git, so the
 JS API and the CLI cannot drift.
 
+### The `share` shorthand
+
+`artifacts share <name>` is the read-side counterpart to `create`.
+It mints a git token for an existing repo and prints just the
+credentialed remote URL on stdout — one clone/push-ready string, no
+JSON envelope — so a caller can hand off a link without parsing
+output or hand-building the URL.
+
+- `--scope` defaults to `read`: the common case is handing a
+  fetch-only link to a consumer. Pass `--scope write` for a
+  pushable URL.
+- `--ttl` takes the same duration grammar as `create`.
+
+The repo must already exist; a missing repo is a hard error (exit 1)
+and no token is minted. The whole printed URL is a secret — it
+carries a live token. Each call mints a fresh token, so revoking one
+shared link does not disturb others.
+
 Help is a first-class, agent-readable surface. `help`, `--help`,
 `-h`, and each group's `--help` print documentation that spells out
 the session-scoping contract and the secret-handling rules. A bare
@@ -201,8 +222,9 @@ the session-scoping contract and the secret-handling rules. A bare
 
 ### Secrets
 
-`token create` and the top-level `create` shorthand print a token's
-`plaintext`, and `repo create` / `import` return an initial `token`.
+`token create` and the `create` shorthand print a token's
+`plaintext`; `share` prints a remote URL with a live token embedded;
+and `repo create` / `import` return an initial `token`.
 The `create` shorthand additionally prints a `credentialedRemote`
 URL with that token embedded — treat the whole URL as a secret.
 `token list` and `token get` show metadata only. Capture a token's

examples/artifacts/README.md

@@ -40,7 +40,7 @@ The Worker endpoint owns the orchestration. The durable object stays minimal: it
 4. initializes and commits the generated project with the shell `git` command;
 5. runs `artifacts create <name> --remote origin --force` — one command that creates the session-scoped Artifact repo, mints a write token, and registers the credentialed remote as `origin`;
 6. pushes `HEAD:main` to `origin`;
-7. creates a short-lived read token with the shell `artifacts` command and returns a clone command.
+7. runs `artifacts share <name> --scope read` — one command that mints a short-lived read token and returns a single clone-ready URL — and returns a clone command built from it.
 
 A successful response looks like:
 
@@ -52,8 +52,7 @@ A successful response looks like:
   "branch": "main",
   "projectDir": "/workspace/my-generated-worker",
   "shareLink": "https://x:<token>@<account>.artifacts.cloudflare.net/git/workspace-artifacts-example/<repo>.git",
-  "cloneCommand": "git clone 'https://x:<token>@<account>.artifacts.cloudflare.net/git/workspace-artifacts-example/<repo>.git' my-generated-worker",
-  "tokenExpiresAt": "2026-06-17T00:00:00.000Z"
+  "cloneCommand": "git clone 'https://x:<token>@<account>.artifacts.cloudflare.net/git/workspace-artifacts-example/<repo>.git' my-generated-worker"
 }
 ```
 

examples/artifacts/src/index.ts

@@ -31,7 +31,6 @@ interface CreateResult {
   projectDir: string;
   shareLink: string;
   cloneCommand: string;
-  tokenExpiresAt: string;
 }
 
 interface ArtifactCreateOutput {
@@ -41,11 +40,6 @@ interface ArtifactCreateOutput {
   credentialedRemote: string;
 }
 
-interface TokenCreateOutput {
-  plaintext: string;
-  expiresAt: string;
-}
-
 const WORKSPACE_ROOT = "/workspace";
 const SOURCE_REPO = "https://github.com/cloudflare/workspace";
 const EXAMPLE_PATH = "examples/worker";
@@ -185,13 +179,12 @@ async function handleCreate(request: Request, env: Env): Promise<Response> {
       secretToRedact: created.credentialedRemote,
     });
 
-    const readToken = parseJSON<TokenCreateOutput>(
-      await exec(
-        ws,
-        `artifacts token create ${shellQuote(name)} --scope read --ttl ${SHARE_TOKEN_TTL}`,
-      ),
-    );
-    const shareLink = authenticatedArtifactRemote(created.remote, readToken.plaintext);
+    // `artifacts share` mints a read token and returns one
+    // clone-ready URL, so there is nothing to hand-assemble. The URL
+    // carries a live token — redact it from any error output.
+    const shareLink = (
+      await exec(ws, `artifacts share ${shellQuote(name)} --scope read --ttl ${SHARE_TOKEN_TTL}`)
+    ).trim();
 
     return Response.json({
       name,
@@ -201,7 +194,6 @@ async function handleCreate(request: Request, env: Env): Promise<Response> {
       projectDir,
       shareLink,
       cloneCommand: `git clone ${shellQuote(shareLink)} ${shellQuote(name)}`,
-      tokenExpiresAt: readToken.expiresAt,
     } satisfies CreateResult);
   } catch (cause) {
     return errorJSON(cause, isAlreadyExists(cause) ? 409 : 500);
@@ -246,11 +238,6 @@ function isAlreadyExists(cause: unknown): boolean {
   );
 }
 
-function authenticatedArtifactRemote(remote: string, token: string): string {
-  const secret = token.split("?expires=", 1)[0];
-  return `https://x:${encodeURIComponent(secret)}@${remote.slice("https://".length)}`;
-}
-
 function errorJSON(error: unknown, status: number): Response {
   const message = error instanceof Error ? error.message : String(error);
   const code = (error as { code?: string }).code;

packages/workspace/src/artifacts/cli.test.ts

@@ -6,7 +6,7 @@
 
 import { beforeEach, describe, expect, it } from "vitest";
 import { FakeArtifactsBinding } from "../../tests/utilities/fake-artifacts-binding.js";
-import { credentialUrl } from "./cli.js";
+import { credentialURL } from "./cli.js";
 import { createArtifact } from "./client.js";
 
 function makeClient() {
@@ -20,9 +20,9 @@ async function run(argv: string[]) {
   return client.cli({ argv });
 }
 
-describe("credentialUrl", () => {
+describe("credentialURL", () => {
   it("embeds the token as basic-auth with the conventional x user", () => {
-    expect(credentialUrl("https://acct.example.net/git/repo.git", "art_v1_abc")).toBe(
+    expect(credentialURL("https://acct.example.net/git/repo.git", "art_v1_abc")).toBe(
       "https://x:art_v1_abc@acct.example.net/git/repo.git",
     );
   });
@@ -31,14 +31,21 @@ describe("credentialUrl", () => {
     // The real binding's plaintext carries a trailing
     // `?expires=<ts>`; folding it in verbatim would corrupt the
     // password and the remote would 401.
-    const url = credentialUrl(
+    const url = credentialURL(
       "https://acct.example.net/git/repo.git",
       "art_v1_secret?expires=1700000000",
     );
     expect(url).toBe("https://x:art_v1_secret@acct.example.net/git/repo.git");
     expect(url).not.toContain("expires");
     expect(new URL(url).password).toBe("art_v1_secret");
   });
+
+  it("splices userinfo textually without round-tripping through new URL", () => {
+    // The remote may be a form workerd's URL parser rejects; the
+    // helper must not depend on `new URL` parsing it.
+    const url = credentialURL("https://h.example.net/git/ns/repo.git", "art_v1_x");
+    expect(url).toBe("https://x:art_v1_x@h.example.net/git/ns/repo.git");
+  });
 });
 
 describe("runArtifactsCLI", () => {
@@ -227,6 +234,66 @@ describe("runArtifactsCLI", () => {
     });
   });
 
+  // `share` mints a token for an existing repo and prints just the
+  // credentialed remote URL on stdout — a single clone/push-ready
+  // string a caller can hand off without parsing JSON.
+  describe("share (shorthand)", () => {
+    it("prints a single credentialed remote URL", async () => {
+      await client.cli({ argv: ["repo", "create", "starter"] });
+      const res = await client.cli({ argv: ["share", "starter", "--scope", "read"] });
+      expect(res.exitCode).toBe(0);
+      const url = res.stdout.trim();
+      // One line, no JSON envelope.
+      expect(url.split("\n")).toHaveLength(1);
+      expect(url.startsWith("https://x:")).toBe(true);
+      expect(url).toContain("art_v1_");
+      expect(url).toContain("sess1__starter.git");
+      // The expires hint must not leak into the password.
+      expect(url).not.toContain("?expires=");
+      const info = await binding.get("sess1__starter");
+      expect(url).toBe(credentialURL(info.remote, new URL(url).password));
+    });
+
+    it("defaults the scope to read", async () => {
+      await client.cli({ argv: ["repo", "create", "starter"] });
+      const res = await client.cli({ argv: ["share", "starter"] });
+      expect(res.exitCode).toBe(0);
+      const tokens = await binding.get("sess1__starter").then((r) => r.listTokens());
+      // Two tokens: the repo-create initial write token, plus this
+      // read share token.
+      const shared = tokens.tokens.find((t) => t.scope === "read");
+      expect(shared).toBeDefined();
+    });
+
+    it("accepts a unit-suffixed --ttl", async () => {
+      await client.cli({ argv: ["repo", "create", "starter"] });
+      const res = await client.cli({ argv: ["share", "starter", "--ttl", "30m"] });
+      expect(res.exitCode).toBe(0);
+    });
+
+    it("exits 129 on a malformed --ttl", async () => {
+      await client.cli({ argv: ["repo", "create", "starter"] });
+      const res = await client.cli({ argv: ["share", "starter", "--ttl", "5w"] });
+      expect(res.exitCode).toBe(129);
+    });
+
+    it("exits 129 on an invalid scope", async () => {
+      await client.cli({ argv: ["repo", "create", "starter"] });
+      const res = await client.cli({ argv: ["share", "starter", "--scope", "admin"] });
+      expect(res.exitCode).toBe(129);
+    });
+
+    it("exits 129 when the name is missing", async () => {
+      const res = await client.cli({ argv: ["share"] });
+      expect(res.exitCode).toBe(129);
+    });
+
+    it("exits 1 when the repo does not exist", async () => {
+      const res = await client.cli({ argv: ["share", "ghost"] });
+      expect(res.exitCode).toBe(1);
+    });
+  });
+
   describe("token list", () => {
     it("prints token metadata without any plaintext", async () => {
       await client.cli({ argv: ["repo", "create", "starter"] });