@seshat.sh/cli 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,71 @@
-# Temporary Holding Version
+# Seshat CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Publish HTML, Markdown, images, PDF, JSON, and other artifacts to your space on [Seshat](https://seshat.sh). Node.js 22 or newer is required. Seshat is an invite-only hosted service; no server clone or Cloudflare account is needed.
+
+```sh
+npx --yes @seshat.sh/cli login
+npx --yes @seshat.sh/cli upload report.html
+```
+
+With pnpm:
+
+```sh
+pnpx @seshat.sh/cli login
+pnpx @seshat.sh/cli upload report.html --title "Weekly report"
+```
+
+Or install once with `npm install --global @seshat.sh/cli`, then run `seshat`.
+
+## Connect a terminal
+
+`login` opens a browser approval page. Check its code, target space, permissions, and credential expiry before approving. The credential is generated locally; the approval API only sees its hash. Login output never contains the token.
+
+Credentials use your OS credential vault. On Linux, a persistent Secret Service store is required. A headless POSIX machine can explicitly use `seshat login --no-browser --storage file`; this keeps its credential in a directory with 0700 permissions and file with 0600 permissions. File mode is not available on Windows; use Credential Manager there. `SESHAT_CONFIG_DIR` overrides the configuration directory.
+
+```sh
+seshat auth status
+seshat whoami
+seshat logout
+```
+
+`seshat whoami` shows your space name and readable permissions:
+
+```text
+✓ Connected to Seshat
+
+  Space     Djamil
+  Access    Read artifacts · Upload and edit
+```
+
+Use `seshat whoami --json` for the space ID, credential ID, and scope values. Use `--json` in scripts and pipelines too.
+
+Logout revokes the connection on Seshat before removing the local credential. Connections are listed under **Agent access → Connected devices**, with their name, permissions, last activity, and expiry. Remove a device there to revoke access immediately; its artifacts remain available. Credentials expire after 90 days by default; `login --expires-at ISO_DATE` chooses a date within the next year.
+
+## Connect an agent
+
+Use a separate profile for each agent or harness. Setup defaults to upload-only access and returns a profile-based upload command, without a token to paste into configuration.
+
+```sh
+seshat agent setup --profile t3 --name "T3 agent" --json
+seshat upload visualizer.html --profile t3 --json
+```
+
+Set `SESHAT_PROFILE=t3` in the harness environment to use that profile automatically. Use `--scopes artifacts:read,artifacts:write` during setup if the agent needs to list or inspect uploads. Existing resource commands remain available; run `seshat --help` and `seshat upload --help` for examples.
+
+For CI without an explicitly selected profile, use `SESHAT_TOKEN` and optional `SESHAT_ENDPOINT`. Explicit `--profile` or `SESHAT_PROFILE` selects its saved credential even when a token is inherited in the environment. Tokens are not accepted as command-line flags. `--endpoint` supports another Seshat instance; stored credentials are never sent to a different endpoint.
+
+## Upload and share
+
+```sh
+seshat upload report.html --title "Weekly report" --request-id weekly-2026-11-09
+cat notes.md | seshat upload - --filename notes.md --content-type text/markdown
+seshat list --limit 20
+```
+
+All commands show readable results and errors by default. Pass `--json` for structured results and errors, including in scripts and pipelines. Login instructions and errors use stderr. Return the upload’s `url` to the user. Reuse a request ID only for retries of the exact same file and metadata. Files may be up to 10 MiB and do not expire by default. HTML should be self-contained. Keep secrets out of shared artifacts.
+
+## Local MCP
+
+`seshat mcp` starts the existing stdio MCP client and reuses the stored profile. Configure `SESHAT_UPLOAD_ROOTS` as a JSON array of allowed directories to enable local file uploads. Without it, inline uploads work and file access is disabled. A hosted MCP endpoint is not provided yet.
+
+This package contains only the service client. Server implementation and deployment sources are not distributed with it.

package/dist/chunk-W3JWSMKV.js

@@ -0,0 +1,3 @@
+import{z as r}from"zod";import{z as V}from"zod";var A=V.enum(["never","hour","day","week","month","year","custom"]);var y=10*1024*1024,D=["artifacts:read","artifacts:write","artifacts:delete","tokens:manage"],b=r.enum(D),l=r.string().regex(/^[a-f0-9]{48}$/),z=r.string().min(8).max(128).regex(/^[A-Za-z0-9_-]+$/),h=r.string().regex(/^seshat_[A-Za-z0-9_-]{43}$/),R=r.iso.datetime().transform(e=>new Date(e).toISOString()),u=r.object({title:r.string().trim().min(1).max(200).optional(),description:r.string().max(2e3).default(""),expiresAt:R.nullable().optional(),expirationPreset:A.nullable().optional(),password:r.string().min(12).max(128).nullable().optional(),generateMetadata:r.boolean().optional()}).strict().refine(e=>e.expirationPreset==null||(e.expirationPreset==="never"?e.expiresAt===null:typeof e.expiresAt=="string"),"Expiration preset must match an explicit expiration value"),F=r.object({filename:r.string().min(1).max(200).regex(/^[^/\\\x00-\x1f\x7f]+$/),contentType:r.string().max(150).regex(/^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/i),size:r.number().int().min(1).max(y)}).strict(),N=r.object({title:u.shape.title.optional(),description:r.string().max(2e3).optional(),expiresAt:u.shape.expiresAt,expirationPreset:u.shape.expirationPreset,password:u.shape.password}).strict().refine(e=>e.expirationPreset==null||(e.expirationPreset==="never"?e.expiresAt===null:typeof e.expiresAt=="string"),"Expiration preset must match an explicit expiration value").refine(e=>Object.values(e).some(t=>t!==void 0),"Provide at least one metadata field"),_=r.object({slug:r.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/).min(2).max(63),name:r.string().trim().min(1).max(100)}).strict(),f=r.object({name:r.string().trim().min(1).max(100),scopes:r.array(b).min(1).max(D.length),expiresAt:R.optional()}).strict(),w=r.object({id:l,title:r.string(),description:r.string(),filename:r.string(),contentType:r.string(),size:r.number(),createdAt:r.string(),expiresAt:r.string().nullable(),expirationPreset:A.nullable().default(null),url:r.url(),downloadUrl:r.url(),passwordProtected:r.boolean().default(!1),views:r.object({owner:r.number(),others:r.number()})}),L=r.object({artifacts:r.array(w),nextCursor:r.string().nullable()}),E=r.object({id:l,token:h,scopes:r.array(b),expiresAt:r.string().nullable()}),P=r.object({space:r.object({id:l,slug:r.string(),name:r.string()}),credential:E}),$=r.object({spaceId:l,tokenId:l,scopes:f.shape.scopes,space:P.shape.space.optional()}),q=r.object({error:r.object({code:r.string(),message:r.string()})});import{z as m}from"zod";import{z as i}from"zod";var M="https://app.seshat.sh",S=i.url().refine(e=>{let t=new URL(e);return!t.username&&!t.password&&!t.search&&!t.hash&&t.pathname==="/"&&(t.protocol==="https:"||t.protocol==="http:"&&["localhost","127.0.0.1","[::1]"].includes(t.hostname))},"Use an HTTPS origin, or HTTP localhost for development").transform(e=>new URL(e).origin),v=i.string().min(1).max(64).regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/),Ae=i.string().max(16).transform(e=>e.toUpperCase().replaceAll("-","").trim()).pipe(i.string().regex(/^[ABCDEFGHJKLMNPQRSTUVWXYZ23456789]{8}$/)),Ee=f.extend({tokenHash:i.string().regex(/^[a-f0-9]{64}$/)}).strict().refine(e=>!e.expiresAt||Date.parse(e.expiresAt)>Date.now()&&Date.parse(e.expiresAt)<=Date.now()+366*864e5,"Choose a credential expiry within the next year"),Pe=i.strictObject({deviceCode:l}),Oe=i.strictObject({approve:i.boolean()}),k=i.object({id:l,slug:i.string(),name:i.string()}),je=i.object({deviceCode:l,userCode:i.string().regex(/^[ABCDEFGHJKLMNPQRSTUVWXYZ23456789]{4}-[ABCDEFGHJKLMNPQRSTUVWXYZ23456789]{4}$/),verificationUrl:i.url(),expiresAt:i.iso.datetime(),interval:i.number().int().min(1).max(60)}),Ce=i.discriminatedUnion("status",[i.object({status:i.literal("pending"),interval:i.number().int().min(1).max(60)}),i.object({status:i.literal("denied")}),i.object({status:i.literal("approved"),id:l,space:k,scopes:f.shape.scopes,expiresAt:i.iso.datetime()})]),Ie=i.object({userCode:i.string(),name:i.string(),scopes:f.shape.scopes,status:i.enum(["pending","approved","denied"]),expiresAt:i.iso.datetime(),tokenExpiresAt:i.iso.datetime(),space:k});var Ue=i.object({devices:i.array(i.object({id:l,name:i.string(),scopes:f.shape.scopes,createdAt:i.iso.datetime(),completedAt:i.iso.datetime().nullable(),lastUsedAt:i.iso.datetime().nullable(),expiresAt:i.iso.datetime().nullable()}))});var ee=m.object({endpoint:S,token:h}).strict(),T=class extends Error{constructor(n,o,a){super(o);this.code=n;this.status=a}code;status},x=class{settings;constructor(t){this.settings=ee.parse(t)}async request(t,n,o={}){let a=new Headers(o.headers);a.set("authorization",`Bearer ${this.settings.token}`),typeof o.body=="string"&&a.set("content-type","application/json");let s;try{s=await fetch(new URL(t,this.settings.endpoint),{...o,headers:a,redirect:"error",signal:o.signal?AbortSignal.any([o.signal,AbortSignal.timeout(6e4)]):AbortSignal.timeout(6e4)})}catch{throw new T("connection_failed","Request failed or timed out. Check SESHAT_ENDPOINT; retry uploads with the same --request-id")}let c=await s.json();if(!s.ok){let d=q.safeParse(c);throw new T(d.success?d.data.error.code:"request_failed",d.success?d.data.error.message:`HTTP ${s.status}`,s.status)}return n.parse(c)}async upload(t){let n=F.parse({filename:t.filename,contentType:t.contentType,size:t.bytes.byteLength}),o=u.parse(t.metadata),a=z.parse(t.requestId),s=new FormData;return s.set("metadata",JSON.stringify(o)),s.set("file",new Blob([new Uint8Array(t.bytes)],{type:n.contentType}),n.filename),this.request("/v1/artifacts",w,{method:"POST",body:s,headers:{"idempotency-key":a}})}list(t={}){let n=new URLSearchParams;return t.limit!==void 0&&n.set("limit",String(t.limit)),t.cursor!==void 0&&n.set("cursor",t.cursor),this.request(`/v1/artifacts?${n}`,L)}get(t){return this.request(`/v1/artifacts/${l.parse(t)}`,w)}update(t,n){return this.request(`/v1/artifacts/${l.parse(t)}`,w,{method:"PATCH",body:JSON.stringify(N.parse(n))})}delete(t){return this.request(`/v1/artifacts/${l.parse(t)}`,m.object({deleted:m.literal(!0),id:l}),{method:"DELETE"})}whoami(t={}){return this.request("/v1/me",$,{signal:t.signal})}completeConnection(){return this.request("/v1/auth/complete",m.object({completed:m.literal(!0)}),{method:"POST"})}revokeSelf(){return this.request("/v1/auth/logout",m.object({revoked:m.literal(!0),id:l}),{method:"POST"})}createSpace(t){return this.request("/v1/admin/spaces",P,{method:"POST",body:JSON.stringify(_.parse(t))})}createToken(t){return this.request("/v1/tokens",E,{method:"POST",body:JSON.stringify(f.parse(t))})}revokeToken(t){return this.request(`/v1/tokens/${l.parse(t)}`,m.object({revoked:m.literal(!0),id:l}),{method:"DELETE"})}};import{constants as H}from"node:fs";import{lstat as te,mkdir as re,open as O,rename as ne,unlink as J}from"node:fs/promises";import{homedir as oe}from"node:os";import{join as g,resolve as ie}from"node:path";import{randomUUID as Y}from"node:crypto";import{setTimeout as ae}from"node:timers/promises";import{z as p}from"zod";var Ze=p.enum(["keychain","file"]),B=p.strictObject({endpoint:S,tokenId:l,space:k,scopes:p.array(b),expiresAt:p.iso.datetime(),pendingConnection:p.literal(!0).optional(),credential:p.discriminatedUnion("kind",[p.strictObject({kind:p.literal("keychain"),account:p.string().min(1)}),p.strictObject({kind:p.literal("file"),token:h})])}),se=p.strictObject({version:p.literal(1),profiles:p.record(v,B)});function X(){return ie(process.env.SESHAT_CONFIG_DIR??g(process.env.XDG_CONFIG_HOME??g(oe(),".config"),"seshat"))}function Z(e){return e instanceof Error&&"code"in e&&e.code==="ENOENT"}async function W(e,t=!1){let n=await te(e);if(n.isSymbolicLink()||(t?!n.isDirectory():!n.isFile()))throw new Error("Seshat credential paths must be real files and directories, not symlinks");if(process.platform!=="win32"&&((n.mode&63)!==0||process.getuid&&n.uid!==process.getuid()))throw new Error(`Credential path must belong to you and have ${t?"0700":"0600"} permissions: ${e}`)}async function G(){let e=X();try{await W(e,!0);let t=g(e,"profiles.json"),n=await O(t,H.O_RDONLY|(H.O_NOFOLLOW??0));try{let o=await n.stat();if(!o.isFile()||o.size>65536||process.platform!=="win32"&&((o.mode&63)!==0||process.getuid&&o.uid!==process.getuid()))throw new Error("Credential file must be a small, owner-only regular file");try{let a=se.safeParse(JSON.parse(await n.readFile("utf8")));if(a.success)return a.data}catch{}throw new Error("Invalid Seshat profile file. Run seshat login again")}finally{await n.close()}}catch(t){if(Z(t))return{version:1,profiles:{}};throw t}}async function C(e,t){let n=X();await re(n,{recursive:!0,mode:448}),await W(n,!0);let o=g(n,"profiles.lock"),a;for(let c=0;c<40;c++)try{a=await O(o,"wx",384);break}catch(d){if(!(d instanceof Error&&"code"in d&&d.code==="EEXIST"))throw d;await ae(50)}if(!a)throw new Error("Another Seshat process is updating profiles. Retry shortly; if it stopped unexpectedly, remove profiles.lock from your Seshat config directory");let s=g(n,`profiles-${Y()}.tmp`);try{t?.throwIfAborted();let c=e(await G()),d=await O(s,"wx",384);try{let U=JSON.stringify(c)+`
+`;if(Buffer.byteLength(U)>65536)throw new Error("Too many stored profiles; remove unused connections before adding another");await d.writeFile(U),await d.sync()}finally{await d.close()}t?.throwIfAborted(),await ne(s,g(n,"profiles.json"))}finally{try{await J(s).catch(c=>{if(!Z(c))throw c})}finally{await a.close(),await J(o)}}}async function I(e){let{AsyncEntry:t}=await import("@napi-rs/keyring");return new t("dev.djamil.seshat.cli",e,{linux:{store:"secret-service"}})}async function j(e){e.credential.kind==="keychain"&&await(await I(e.credential.account)).deletePassword(AbortSignal.timeout(15e3))}async function We(e){let t=v.parse(e.name),n=h.parse(e.token);if(e.storage==="file"&&process.platform==="win32")throw new Error("Use keychain storage with Windows Credential Manager");let o=Y();if(e.storage==="keychain")try{await(await I(o)).setPassword(n,e.signal?AbortSignal.any([e.signal,AbortSignal.timeout(15e3)]):AbortSignal.timeout(15e3))}catch{throw e.signal?.aborted?new Error("Connection cancelled"):new Error("The OS credential vault is unavailable. On a headless POSIX machine, rerun login with --storage file to use an owner-only credential file")}let a=B.parse({pendingConnection:e.pendingConnection,endpoint:e.endpoint,tokenId:e.tokenId,space:e.space,scopes:e.scopes,expiresAt:e.expiresAt,credential:e.storage==="keychain"?{kind:"keychain",account:o}:{kind:"file",token:n}}),s;try{await C(c=>{if(s=Object.hasOwn(c.profiles,t)?c.profiles[t]:void 0,(s?.tokenId??null)!==e.expectedTokenId)throw new Error("This profile changed during login. Retry; the newer connection has been preserved");return{...c,profiles:{...c.profiles,[t]:a}}},e.signal)}catch(c){throw await j(a).catch(()=>{}),c}return s&&await j(s).catch(()=>{process.stderr.write(`The previous OS credential entry could not be removed. Revoke its token in Seshat Agent access.
+`)}),a}function ce(e){return v.parse(e??process.env.SESHAT_PROFILE??"default")}async function K(e){let t=await G();return Object.hasOwn(t.profiles,e)?t.profiles[e]:void 0}async function le(e){if(e.credential.kind==="file")return e.credential.token;try{return h.parse(await(await I(e.credential.account)).getPassword(AbortSignal.timeout(15e3)))}catch{throw new Error("Stored credential is unavailable. Run seshat login again for this profile")}}async function Ge(e,t){let n=await K(e);if(n){if(n.tokenId!==t)throw new Error("This profile changed during logout. The newer connection has been preserved");await j(n),await C(o=>{let a=Object.hasOwn(o.profiles,e)?o.profiles[e]:void 0;if(a&&a.tokenId!==t)throw new Error("This profile changed during logout. The newer connection has been preserved");let s={...o.profiles};return delete s[e],{...o,profiles:s}})}}async function pe(e,t,n){t.pendingConnection&&(await n.completeConnection(),await C(o=>{let a=Object.hasOwn(o.profiles,e)?o.profiles[e]:void 0;if(a?.tokenId!==t.tokenId)throw new Error("This profile changed during connection. The newer connection has been preserved");let{pendingConnection:s,...c}=a;return{...o,profiles:{...o.profiles,[e]:c}}}))}async function Ke(e={}){let t=e.endpoint??process.env.SESHAT_ENDPOINT;if(process.env.SESHAT_TOKEN&&!e.profile&&!process.env.SESHAT_PROFILE)return new x({endpoint:t??M,token:process.env.SESHAT_TOKEN});let n=ce(e.profile),o=await K(n);if(!o)throw new Error(`No credential for profile "${n}". Run seshat login --profile ${n}`);if(t&&S.parse(t)!==o.endpoint)throw new Error("This profile belongs to another endpoint. Log in with a different --profile; stored credentials are never sent to a different service");let a=new x({endpoint:o.endpoint,token:await le(o)});return await pe(n,o,a),a}function Qe(e,t){return{profile:e,endpoint:t.endpoint,tokenId:t.tokenId,space:t.space,scopes:t.scopes,expiresAt:t.expiresAt,storage:t.credential.kind}}import{realpath as Q,stat as de,readFile as me}from"node:fs/promises";import{basename as fe,extname as he,relative as ue,isAbsolute as ge}from"node:path";var we={".html":"text/html",".htm":"text/html",".md":"text/markdown",".markdown":"text/markdown",".json":"application/json",".pdf":"application/pdf",".png":"image/png",".jpg":"image/jpeg",".jpeg":"image/jpeg",".gif":"image/gif",".webp":"image/webp",".svg":"image/svg+xml",".txt":"text/plain"};async function nt(e,t){let n=await Q(e);if(t&&!(await Promise.all(t.map(s=>Q(s)))).some(s=>{let c=ue(s,n);return c!==".."&&!c.startsWith("../")&&!ge(c)}))throw new Error("File is outside SESHAT_UPLOAD_ROOTS. Configure explicit directories for MCP file access");let o=await de(n);if(!o.isFile())throw new Error("Upload path must be a regular file");if(o.size<1||o.size>y)throw new Error(`File must contain 1 to ${y} bytes`);return{bytes:new Uint8Array(await me(n)),filename:fe(n),contentType:we[he(n).toLowerCase()]??"application/octet-stream"}}export{y as a,b,l as c,z as d,u as e,N as f,q as g,M as h,S as i,je as j,Ce as k,T as l,x as m,Ze as n,We as o,ce as p,K as q,le as r,Ge as s,pe as t,Ke as u,Qe as v,nt as w};

package/dist/cli.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+import{a as U,b as O,d as W,g as G,h as q,i as F,j as X,k as j,l as T,m as A,n as Y,o as Z,p as x,q as D,r as L,s as V,t as H,u as C,v as N,w as Q}from"./chunk-W3JWSMKV.js";import{parseArgs as ge}from"node:util";import{pathToFileURL as we}from"node:url";import{realpathSync as ye}from"node:fs";import{z as $}from"zod";import{stripVTControlCharacters as ce}from"node:util";function b(e){return ce(e).replace(/[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/g," ").trim()}function P(e){return e?new Date(e).toLocaleDateString(void 0,{month:"short",day:"numeric",year:"numeric"}):"Never"}function d(e,n=[]){return`
+${b(e)}
+${n.length?`
+`+n.map(([o,c])=>`  ${o.padEnd(10)}${b(c)}`).join(`
+`)+`
+`:""}`}function I(e){let n={"artifacts:read":"Read artifacts","artifacts:write":"Upload and edit","artifacts:delete":"Delete artifacts","tokens:manage":"Manage tokens"};return e.map(o=>n[o]).join(" \xB7 ")}function K(e,n,o){let c=e.profile==="default"?"":` --profile ${e.profile}`;return d(`${n?"\u2713 Already connected to":"\u2713 Connected to"} ${e.space.name}`,[["Profile",e.profile],["Service",e.endpoint],["Access",I(e.scopes)],["Expires",P(e.expiresAt)],["Stored in",e.storage==="keychain"?"OS credential vault":"Private credential file (0600)"],[o?"Agent uses":"Try next",`seshat upload ./report.html${c}${o?" --json":""}`]])}function R(e,n){return d(`${n} ${e.title}`,[["Link",e.url],["File",e.filename],["Size",`${new Intl.NumberFormat().format(e.size)} bytes`],["Expires",P(e.expiresAt)]])}function ee(e,n){return process.env.NO_COLOR!==void 0||process.env.TERM==="dumb"?e:e.replace(/^([✓✕].*)$/m,o=>`\x1B[1;${n}m${o}\x1B[0m`)}function _(e,n,o){process.stdout.write(o?(process.stdout.isTTY?ee(n,32):n)+`
+`:JSON.stringify(e)+`
+`)}function te(e,n){if(!n){process.stderr.write(JSON.stringify({error:{code:e.code,message:e.message},...e.requestId?{requestId:e.requestId}:{}})+`
+`);return}let o=d(`\u2715 ${e.message}`,[["Code",e.code],...e.hint?[["Next step",e.hint]]:[],...e.requestId?[["Retry ID",e.requestId]]:[]]);process.stderr.write((process.stderr.isTTY?ee(o,31):o)+`
+`)}import{randomBytes as pe,createHash as le}from"node:crypto";import{execFile as de}from"node:child_process";import{promisify as ue}from"node:util";import{hostname as fe}from"node:os";import{setTimeout as me}from"node:timers/promises";import{z as re}from"zod";var z=ue(de);async function B(e,n,o,c,h){let r=await fetch(e+n,{method:"POST",redirect:"error",headers:{"content-type":"application/json"},body:JSON.stringify(o),signal:h?AbortSignal.any([h,AbortSignal.timeout(15e3)]):AbortSignal.timeout(15e3)}),a=await r.json();if(!r.ok){let u=G.safeParse(a);throw new T(u.success?u.data.error.code:"connection_failed",u.success?u.data.error.message:"Could not connect to Seshat",r.status)}let f=c.safeParse(a);if(!f.success)throw new Error("Unexpected connection response from the service");return f.data}async function he(e){process.platform==="darwin"?await z("open",[e],{timeout:1e4}):process.platform==="win32"?await z("rundll32",["url.dll,FileProtocolHandler",e],{timeout:1e4}):await z("xdg-open",[e],{timeout:1e4})}async function ne(e){let n=x(e.profile),o=F.parse(e.endpoint??process.env.SESHAT_ENDPOINT??q),c=Y.parse(e.storage??"keychain");if(c==="file"&&process.platform==="win32")throw new Error("Use keychain storage with Windows Credential Manager");let h=re.array(O).min(1).parse((e.scopes??"artifacts:read,artifacts:write").split(",")),r=re.coerce.number().int().min(5).max(600).parse(e.timeout??600),a=await D(n),f;if(a){try{f=new A({endpoint:a.endpoint,token:await L(a)})}catch{}if(!e.force&&e.expiresAt===void 0&&e.name===void 0&&(e.storage===void 0||e.storage===a.credential.kind)&&f&&a.endpoint===o&&a.expiresAt>new Date().toISOString()&&[...new Set(h)].sort().join(",")===[...a.scopes].sort().join(","))try{return await H(n,a,f),await f.whoami(),{connected:!0,alreadyConnected:!0,...N(n,a)}}catch(p){if(!(p instanceof T&&p.status===401))throw p}}let u="seshat_"+pe(32).toString("base64url"),S=le("sha256").update(u).digest("hex"),s=await B(o,"/v1/auth/device",{name:e.name??`${fe().slice(0,60)} \xB7 ${n.slice(0,32)}`,scopes:h,tokenHash:S,...e.expiresAt?{expiresAt:e.expiresAt}:{}},X);if(!URL.canParse(s.verificationUrl))throw new Error("The service returned an invalid authorization URL");let k=new URL(s.verificationUrl);if(k.origin!==o||k.pathname!=="/connect"||k.username||k.password||k.hash||k.searchParams.get("code")!==s.userCode)throw new Error("The service returned an unexpected authorization URL");process.stderr.write(e.human?d("Connect this terminal to Seshat",[["Open",s.verificationUrl],["Code",s.userCode]])+`
+  Check the code in your browser, then approve this device.
+  Waiting for approval\u2026
+
+`:`Approve this terminal in Seshat:
+${s.verificationUrl}
+Code: ${s.userCode}
+`),e.noBrowser||await he(s.verificationUrl).catch(()=>process.stderr.write(`Open the URL above in your browser to continue.
+`));let y=new AbortController,m=()=>y.abort();process.once("SIGINT",m);let v=Math.min(Date.parse(s.expiresAt),Date.now()+r*1e3),E=!1;try{let p=s.interval;for(;Date.now()<v&&(await me(Math.min(p*1e3,Math.max(0,v-Date.now())),void 0,{signal:y.signal}),!(Date.now()>=v));){let i;try{i=await B(o,"/v1/auth/device/poll",{deviceCode:s.deviceCode},j,y.signal)}catch(g){if(g instanceof T&&g.code==="slow_down"){p+=2;continue}throw g}if(i.status==="denied")throw new Error("Connection was denied. No credential was saved");if(i.status==="pending"){p=i.interval;continue}let t=await new A({endpoint:o,token:u}).whoami({signal:y.signal});if(t.spaceId!==i.space.id||t.tokenId!==i.id||[...new Set(h)].sort().join(",")!==[...t.scopes].sort().join(","))throw new Error("The approved credential does not match the requested space and permissions");y.signal.throwIfAborted();let l=await Z({name:n,endpoint:o,tokenId:i.id,token:u,space:i.space,scopes:i.scopes,expiresAt:i.expiresAt,storage:c,pendingConnection:!0,expectedTokenId:a?.tokenId??null,signal:y.signal});E=!0;try{await H(n,l,new A({endpoint:o,token:u}))}catch{throw new Error("Credential saved, but connection completion was interrupted. Retry seshat auth status with this --profile to finish, or login --force if its five-minute approval expired")}return f&&await f.revokeSelf().catch(()=>process.stderr.write(`The previous credential could not be revoked. Revoke it in Seshat Agent access.
+`)),{connected:!0,...N(n,l)}}throw new Error("Connection approval timed out. Run seshat login again")}finally{process.removeListener("SIGINT",m),E||await B(o,"/v1/auth/device/cancel",{deviceCode:s.deviceCode},j).catch(()=>{})}}async function oe(e){let n=x(e),o=await D(n);if(!o)return{disconnected:!0,alreadyDisconnected:!0,profile:n};try{await new A({endpoint:o.endpoint,token:await L(o)}).revokeSelf()}catch(c){if(!(c instanceof T&&c.status===401))throw new Error("Could not revoke this connection. Retry logout when the service is available; the local credential has been kept")}return await V(n,o.tokenId),{disconnected:!0,profile:n}}async function se(e={}){let n=x(e.profile);if(process.env.SESHAT_TOKEN&&!e.profile&&!process.env.SESHAT_PROFILE){let h=await(await C(e)).whoami();return{connected:!0,source:"environment",endpoint:F.parse(e.endpoint??process.env.SESHAT_ENDPOINT??q),...h}}let o=await D(n);if(!o)return{connected:!1,profile:n};let c=await(await C(e)).whoami();return{connected:!0,...N(n,o),...c}}var M={root:`Seshat: publish and manage agent artifacts.
+
+Commands default to human-readable output. Use --json for structured results and errors.
+
+Commands:
+  login             Connect this terminal through your browser
+  upload FILE       Publish an artifact and return its share link
+  list              List your artifacts
+  whoami            Show the connected space and permissions
+  logout            Revoke this connection and remove its credential
+  agent setup       Create a separate, named connection for an agent
+  auth status       Check a stored connection without exposing credentials
+  artifacts upload|list|get|update|delete
+  tokens create|revoke
+  spaces create
+  auth whoami
+  mcp
+
+The default service is https://app.seshat.sh. Run seshat login once.
+Use --profile NAME for separate user/agent connections. CI may set SESHAT_ENDPOINT and SESHAT_TOKEN.
+Tokens are never accepted in command-line flags.
+Run a command with --help for examples.
+
+Examples:
+  seshat login
+  seshat upload report.html --title "Weekly report"
+  seshat agent setup --profile t3 --name "T3 agent"
+  seshat list --limit 20
+  seshat whoami`,"artifacts upload":`Upload one file, or stdin with path -. Links are public and unlisted. Files do not expire by default. Blank metadata is generated automatically.
+Options: --title (optional), --description, --content-type, --filename (stdin), --request-id, --expires-at, --no-expiry
+Keep --request-id stable across retries. Reusing it with different content returns a conflict.
+Examples:
+  seshat artifacts upload report.html --title "Weekly report" --request-id report-2026-11-08
+  cat notes.md | seshat artifacts upload - --filename notes.md --content-type text/markdown --title Notes`,"artifacts list":`List uploads in your token's space. Options: --limit (1-100), --cursor.
+Examples:
+  seshat artifacts list --limit 20
+  seshat artifacts list --cursor RETURNED_NEXT_CURSOR`,"artifacts get":`Get metadata and view counts. Requires artifacts:read.
+Example: seshat artifacts get ARTIFACT_ID`,"artifacts update":`Update metadata. Options: --title, --description, --expires-at, --no-expiry.
+Example: seshat artifacts update ARTIFACT_ID --title "Updated report"`,"artifacts delete":`Delete an upload. Requires --yes. Use --dry-run to inspect the target.
+Examples:
+  seshat artifacts delete ARTIFACT_ID --dry-run
+  seshat artifacts delete ARTIFACT_ID --yes`,"tokens create":`Create a credential for this space. Secret is returned once. Requires tokens:manage.
+Options: --name (required), --scopes (comma-separated; default artifacts:write), --expires-at.
+Example: seshat tokens create --name t3 --scopes artifacts:write,artifacts:read`,"tokens revoke":`Revoke a credential immediately. Requires tokens:manage and --yes.
+Examples:
+  seshat tokens revoke TOKEN_ID --dry-run
+  seshat tokens revoke TOKEN_ID --yes`,"spaces create":`Operator bootstrap: create a space and return its owner credential once.
+Set SESHAT_TOKEN to the deployment's administrator credential. This does not send an invitation.
+Example: seshat spaces create --slug djamil --name Djamil`,"auth login":`Connect a terminal through browser approval. A Seshat invitation is required.
+Options: --profile (default default), --endpoint, --name, --scopes (default artifacts:read,artifacts:write), --expires-at (default 90 days), --storage keychain|file, --no-browser, --timeout (5-600 seconds), --force.
+OS credential storage is the default. On headless POSIX machines, --storage file explicitly selects an owner-only file.
+The approval URL and code go to stderr. Success shows your space, profile, expiry and storage. Use --json for secret-free structured output.
+Examples:
+  seshat login
+  seshat login --no-browser --profile remote --storage file
+  seshat login --profile reviewer --scopes artifacts:read`,"auth logout":`Revoke a saved connection and remove its local credential. Requires access to the service.
+Example: seshat logout --profile t3`,"auth status":`Check a stored profile and its live credential. Never prints the token.
+Example: seshat auth status --profile t3`,"agent setup":`Create a separate named agent connection. Defaults to the agent profile and upload-only permission.
+Options: --profile, --name, --endpoint, --scopes, --expires-at, --storage keychain|file, --no-browser, --timeout, --force.
+After approval, the output includes a profile-based upload command. No token needs copying into a harness.
+Examples:
+  seshat agent setup --profile t3 --name "T3 agent"
+  seshat agent setup --profile remote --storage file --no-browser`,"auth whoami":`Inspect the active token's space and scopes.
+Example: seshat auth whoami`,mcp:`Start the local stdio MCP server. SESHAT_UPLOAD_ROOTS is an optional JSON array of allowed directories.
+Example: seshat mcp`},ve={help:{type:"boolean"},json:{type:"boolean"},title:{type:"string"},description:{type:"string"},"content-type":{type:"string"},filename:{type:"string"},"request-id":{type:"string"},"expires-at":{type:"string"},"no-expiry":{type:"boolean"},limit:{type:"string"},cursor:{type:"string"},yes:{type:"boolean"},"dry-run":{type:"boolean"},name:{type:"string"},scopes:{type:"string"},slug:{type:"string"},profile:{type:"string"},endpoint:{type:"string"},storage:{type:"string"},"no-browser":{type:"boolean"},timeout:{type:"string"},force:{type:"boolean"}},ke={"artifacts upload":["title","description","content-type","filename","request-id","expires-at","no-expiry"],"artifacts list":["limit","cursor"],"artifacts get":[],"artifacts update":["title","description","expires-at","no-expiry"],"artifacts delete":["yes","dry-run"],"tokens create":["name","scopes","expires-at"],"tokens revoke":["yes","dry-run"],"spaces create":["slug","name"],"auth whoami":[],"auth login":["name","scopes","expires-at","storage","no-browser","timeout","force"],"agent setup":["name","scopes","expires-at","storage","no-browser","timeout","force"],"auth logout":[],"auth status":[],mcp:[]};function w(e,n){let o=$.string().min(1).safeParse(e);if(!o.success)throw new Error(`Provide ${n}. Run this command with --help for an example`);return o.data}async function xe(){let e=[],n=0;for await(let o of process.stdin){let c=Buffer.from(o);if(n+=c.length,n>U)throw new Error(`stdin exceeds ${U} bytes`);e.push(c)}return new Uint8Array(Buffer.concat(e))}async function Se(e){let n,o=!e.includes("--json"),c="default",h="seshat --help";try{let{values:r,positionals:a}=ge({args:e,options:ve,allowPositionals:!0}),f={login:"auth login",logout:"auth logout",whoami:"auth whoami",upload:"artifacts upload",list:"artifacts list"},u=a[0]??"",S=Object.hasOwn(f,u)?f[u]:void 0,s=S??(u==="mcp"?"mcp":a.slice(0,2).join(" "));if(r.help||!s){process.stdout.write((M[s]??M.root)+(s?`
+
+Output: human-readable by default. Use --json for structured results and errors.`:"")+`
+`);return}if(!M[s])throw new Error("Unknown command. Run seshat --help");h=`seshat ${s} --help`,c=x(r.profile??(s==="agent setup"?"agent":void 0));let k=["artifacts upload","artifacts get","artifacts update","artifacts delete","tokens revoke"].includes(s);if(a.length>(s==="mcp"?1:(S?1:2)+(k?1:0)))throw new Error("Unexpected positional argument. Run this command with --help");let y=Object.keys(r).find(t=>!["help","json","profile","endpoint",...ke[s]??[]].includes(t));if(y)throw new Error(`--${y} is not supported by ${s}. Run this command with --help`);if(s==="mcp"){let{startMcp:t}=await import("./mcp.js");await t({profile:r.profile,endpoint:r.endpoint});return}if(r["no-expiry"]&&r["expires-at"])throw new Error("Choose --no-expiry or --expires-at");if(s==="auth login"||s==="agent setup"){let t=s==="agent setup"?x(r.profile??"agent"):x(r.profile),l=await ne({profile:t,endpoint:r.endpoint,name:r.name,scopes:r.scopes??(s==="agent setup"?"artifacts:write":void 0),expiresAt:r["expires-at"],storage:r.storage,noBrowser:r["no-browser"],timeout:r.timeout,force:r.force,human:o}),g=s==="agent setup"?{...l,agent:{environment:{SESHAT_PROFILE:t},uploadCommand:`pnpx @seshat.sh/cli upload FILE --profile ${t} --json`,helpCommand:"pnpx @seshat.sh/cli upload --help"}}:l;_(g,K(l,"alreadyConnected"in l&&!!l.alreadyConnected,s==="agent setup"),o);return}if(s==="auth logout"||s==="auth status"){let t=s==="auth logout"?await oe(r.profile):await se({profile:r.profile,endpoint:r.endpoint}),l="disconnected"in t?d(t.alreadyDisconnected?"\u2713 No saved connection":"\u2713 Device disconnected",[["Profile",t.profile]]):t.connected?"storage"in t?K(t,!0,!1):d("\u2713 Connected with SESHAT_TOKEN",[["Service",t.endpoint],["Space",t.space?.name??t.spaceId],["Access",I(t.scopes)]]):d("No connected device",[["Profile",t.profile],["Next step",`seshat login --profile ${t.profile}`]]);_(t,l,o);return}let m=await C({profile:r.profile,endpoint:r.endpoint}),v=a[S?1:2],E=r["no-expiry"]?null:r["expires-at"],p,i="";switch(s){case"auth whoami":{let t=await m.whoami();p={spaceId:t.spaceId,tokenId:t.tokenId,scopes:t.scopes},i=d("\u2713 Connected to Seshat",[["Space",t.space?.name??t.spaceId],["Access",I(t.scopes)]]);break}case"spaces create":{let t=await m.createSpace({slug:w(r.slug,"--slug"),name:w(r.name,"--name")});p=t,i=d(`\u2713 Created ${t.space.name}`,[["Space ID",t.space.id],["Token",t.credential.token],["Keep safe","Copy this token now. It will not be shown again."]]);break}case"tokens create":{let t=await m.createToken({name:w(r.name,"--name"),scopes:$.array(O).parse((r.scopes??"artifacts:write").split(",")),expiresAt:r["expires-at"]});p=t,i=d("\u2713 Token created",[["Token",t.token],["Access",I(t.scopes)],["Expires",P(t.expiresAt)],["Keep safe","Copy this token now. It will not be shown again."]]);break}case"tokens revoke":{let t=w(v,"TOKEN_ID");if(r["dry-run"]){p={dryRun:!0,action:"revoke_token",id:t},i=d("Preview: revoke token",[["Token ID",t],["To apply",`seshat tokens revoke ${t} --yes`]]);break}if(!r.yes)throw new Error("Revocation requires --yes. Inspect with seshat tokens revoke TOKEN_ID --dry-run");p=await m.revokeToken(t),i=d("\u2713 Token revoked",[["Token ID",t]]);break}case"artifacts list":{let t=await m.list({limit:r.limit===void 0?void 0:$.coerce.number().int().min(1).max(100).parse(r.limit),cursor:r.cursor});p=t,i=d(t.artifacts.length?`${t.artifacts.length} artifacts`:"No artifacts yet")+t.artifacts.map(l=>`
+  ${b(l.title)}
+  ${b(l.url)}
+`).join("")+(t.nextCursor?`
+  Next page: seshat list --cursor ${b(t.nextCursor)}
+`:"");break}case"artifacts get":{let t=await m.get(w(v,"ARTIFACT_ID"));p=t,i=R(t,"Artifact:");break}case"artifacts update":{let t=await m.update(w(v,"ARTIFACT_ID"),{title:r.title,description:r.description,expiresAt:E});p=t,i=R(t,"\u2713 Updated");break}case"artifacts delete":{let t=w(v,"ARTIFACT_ID");if(r["dry-run"]){let l=await m.get(t);p={dryRun:!0,action:"delete_artifact",artifact:l},i=R(l,"Preview: delete")+`
+  To apply: seshat artifacts delete ${t} --yes
+`;break}if(!r.yes)throw new Error("Deletion requires --yes. Inspect with seshat artifacts delete ARTIFACT_ID --dry-run");p=await m.delete(t),i=d("\u2713 Artifact deleted",[["ID",t]]);break}case"artifacts upload":{let t=w(v,"FILE or - for stdin"),l=r.title;n=W.parse(r["request-id"]??crypto.randomUUID());let g;if(t==="-"){let ae=w(r.filename,"--filename for stdin"),ie=w(r["content-type"],"--content-type for stdin");g={bytes:await xe(),filename:ae,contentType:ie}}else g=await Q(t);let J=await m.upload({...g,contentType:r["content-type"]??g.contentType,metadata:{title:l,description:r.description??"",expiresAt:E},requestId:n});p={...J,requestId:n},i=R(J,"\u2713 Uploaded");break}}_(p,i,o)}catch(r){let a=r instanceof T?r.code:"invalid_command",f=r instanceof $.ZodError?`Invalid options: ${r.issues.map(S=>S.message).join("; ")}. Run ${h}`:r instanceof Error?r.message:"Command failed",u=a==="unauthorized"?`Reconnect with seshat login --profile ${c}, or check SESHAT_TOKEN if you use it.`:a==="insufficient_scope"?`Reconnect with the required --scopes using seshat login --profile ${c}.`:a==="connection_failed"?"Check your connection and service endpoint. Retry uploads with the same --request-id.":void 0;te({code:a,message:f,requestId:n,hint:u},o),process.exitCode=1}}process.argv[1]&&import.meta.url===we(ye(process.argv[1])).href&&await Se(process.argv.slice(2));export{Se as runCli};

package/dist/mcp.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import{c as s,d as l,e as o,f as c,u,w as p}from"./chunk-W3JWSMKV.js";import{pathToFileURL as f}from"node:url";import{realpathSync as S}from"node:fs";import{McpServer as g}from"@modelcontextprotocol/sdk/server/mcp.js";import{StdioServerTransport as y}from"@modelcontextprotocol/sdk/server/stdio.js";import{z as a}from"zod";var m=`Seshat publishes artifacts to public, unlisted links. Upload only content the user wants shared.
+Run seshat login once to use a stored profile. SESHAT_PROFILE selects a named agent profile. For CI, set SESHAT_ENDPOINT and a tenant-scoped SESHAT_TOKEN, never in tool arguments.
+Supported readers: interactive HTML, Markdown, images, PDF, JSON, and plain text. Other formats download.
+Artifacts do not expire by default. Set expiresAt to an ISO date to expire one, or null for no expiration. Omit title or description to generate metadata automatically on Cloudflare; explicit values are preserved. Set metadata.password to a password of 12\u2013128 characters to protect an upload. Update password to null to remove protection; changing it invalidates previous unlocks.
+Use a stable requestId for the same logical upload. Retrying identical bytes and metadata returns the original artifact.
+A different payload with the same requestId is rejected. Uploading a changed version requires a new requestId.
+Use upload_file for local artifacts. File access requires SESHAT_UPLOAD_ROOTS, a JSON array of allowed directories.
+Use upload_text for inline content. Generate self-contained HTML with embedded assets; directory bundles are not supported yet.
+Return the artifact url to the user. Never return bearer tokens or put them in share URLs.
+Listing and details require artifacts:read, uploads and edits require artifacts:write, deletion requires artifacts:delete.
+View counts are page requests. Owners count separately only when authenticated; logged-out owners count as others. Bots are not filtered yet.`;function w(t){return{content:[{type:"text",text:JSON.stringify(t)}],structuredContent:{result:t}}}async function i(t){try{return w(await t())}catch(n){return{content:[{type:"text",text:n instanceof Error?n.message:"Tool failed"}],isError:!0}}}function T(t,n=[]){let r=new g({name:"seshat",version:"0.1.0"},{instructions:m});r.registerResource("guide","seshat://guide",{description:"Upload formats, authorization scopes, expiration, retry semantics, and share-link behavior",mimeType:"text/plain"},async e=>({contents:[{uri:e.href,mimeType:"text/plain",text:m}]}));let d=l.describe("Stable ID for this logical upload. Reuse unchanged when retrying");return r.registerTool("seshat_upload_text",{description:"Publish inline HTML, Markdown, JSON, or text and return a public unlisted share URL. No expiration by default; missing titles and descriptions are generated automatically. Maximum 10 MiB. Do not upload secrets.",inputSchema:{content:a.string().min(1).max(10*1024*1024),filename:a.string(),contentType:a.enum(["text/html","text/markdown","application/json","text/plain"]),metadata:o,requestId:d},annotations:{destructiveHint:!1,idempotentHint:!0,openWorldHint:!0}},async e=>i(async()=>({...await t.upload({bytes:new TextEncoder().encode(e.content),filename:e.filename,contentType:e.contentType,metadata:e.metadata,requestId:e.requestId}),requestId:e.requestId}))),r.registerTool("seshat_upload_file",{description:"Publish a local file up to 10 MiB and return a public unlisted share URL. Path must be inside configured SESHAT_UPLOAD_ROOTS. HTML must be self-contained. Do not upload secrets.",inputSchema:{path:a.string().min(1),metadata:o,requestId:d},annotations:{destructiveHint:!1,idempotentHint:!0,openWorldHint:!0}},async e=>i(async()=>{if(!n.length)throw new Error("File uploads are disabled. Set SESHAT_UPLOAD_ROOTS to a JSON array of allowed directories, or use seshat_upload_text");return{...await t.upload({...await p(e.path,n),metadata:e.metadata,requestId:e.requestId}),requestId:e.requestId}})),r.registerTool("seshat_list_artifacts",{description:"List artifacts in the authorized space, including share links and expiration. Follow nextCursor for more results. Requires artifacts:read.",inputSchema:{limit:a.number().int().min(1).max(100).optional(),cursor:a.string().optional()},annotations:{readOnlyHint:!0,destructiveHint:!1,openWorldHint:!0}},async e=>i(()=>t.list(e))),r.registerTool("seshat_get_artifact",{description:"Get an artifact's metadata, URL, and owner/other page-request counts. Requires artifacts:read.",inputSchema:{id:s},annotations:{readOnlyHint:!0,destructiveHint:!1,openWorldHint:!0}},async({id:e})=>i(()=>t.get(e))),r.registerTool("seshat_update_artifact",{description:"Edit title, description, expiration, or password protection in the authorized space. Omitted fields stay unchanged. expiresAt:null disables expiration. Requires artifacts:write.",inputSchema:{id:s,changes:c},annotations:{destructiveHint:!0,idempotentHint:!0,openWorldHint:!0}},async({id:e,changes:h})=>i(()=>t.update(e,h))),r.registerTool("seshat_delete_artifact",{description:"Permanently delete an artifact and invalidate its share link. Call only when the user requests deletion. Requires artifacts:delete and confirm:true.",inputSchema:{id:s,confirm:a.literal(!0)},annotations:{destructiveHint:!0,idempotentHint:!0,openWorldHint:!0}},async({id:e})=>i(()=>t.delete(e))),r}async function x(t={}){let n=JSON.parse(process.env.SESHAT_UPLOAD_ROOTS??"[]");await T(await u(t),a.array(a.string().min(1)).parse(n)).connect(new y)}if(process.argv[1]&&import.meta.url===f(S(process.argv[1])).href)try{await x()}catch{process.stderr.write(`Seshat MCP could not start. Run seshat login, or check SESHAT_PROFILE, SESHAT_TOKEN, and SESHAT_UPLOAD_ROOTS
+`),process.exitCode=1}export{m as agentGuide,T as createMcpServer,x as startMcp};

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "@seshat.sh/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Publish and share artifacts with Seshat from terminals and agents.",
+  "type": "module",
+  "license": "UNLICENSED",
+  "homepage": "https://seshat.sh",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "seshat": "dist/cli.js"
+  },
+  "files": [
+    "dist/**/*.js",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.32.2",
+    "@napi-rs/keyring": "2.1.2",
+    "zod": "4.6.7"
+  }
+}