@journoid/cli 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Journoid contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,33 @@
-# Temporary Holding Version
+# Journoid 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.
+Use your terminal or an agent to read and change your Journoid data.
+Requires Node.js 22.14 or later.
+
+```sh
+pnpm add -g @journoid/cli
+journoid login
+journoid blocks
+journoid actions
+journoid actions create-todo
+journoid call create-todo --input '{"title":"Try Journoid from my terminal"}'
+```
+
+Data commands return JSON. `--json` is accepted for agent scripts. Discover an
+action's exact schema before calling it. Custom block schemas come from `blocks`.
+Use `--input-file path.json`, or `--input-file -` to read JSON from stdin.
+
+Full access includes permanent deletion. The connected agent supplies its own
+reasoning; ordinary data operations make no extra model request. If a write loses
+its response, inspect saved data before retrying. Writes are not automatically
+retried after network failures.
+
+Credentials stay in a private file under your user configuration directory.
+Use `journoid logout` to revoke the CLI session. Settings > Your agents can
+disconnect access immediately, or allow access again after disconnecting.
+Expired sessions refresh automatically when possible; otherwise run `login`.
+
+For remote MCP clients, use `https://journoid.app/mcp` with OAuth instead of
+installing the CLI. Settings provides setup commands for supported clients.
+
+For an isolated local backend, use `--url http://localhost:<app-port>` on each
+command. Credentials are kept separately for each server origin.

package/bin/journoid.mjs

@@ -0,0 +1,449 @@
+#!/usr/bin/env node
+import {
+  readFile,
+  writeFile,
+  mkdir,
+  rename,
+  chmod,
+  unlink,
+  realpath,
+} from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join, dirname } from 'node:path'
+import { randomUUID } from 'node:crypto'
+import { spawn } from 'node:child_process'
+import { pathToFileURL } from 'node:url'
+import lockfile from 'proper-lockfile'
+
+function secureUrl(value) {
+  const url = new URL(value)
+  if (
+    url.protocol !== 'https:' &&
+    !(
+      url.protocol === 'http:' &&
+      ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)
+    )
+  )
+    throw new Error('Use HTTPS, or a loopback URL for local development.')
+  if (url.username || url.password)
+    throw new Error('URLs must not contain credentials.')
+  return url
+}
+
+export class JournoidClient {
+  constructor({
+    origin = process.env.JOURNOID_URL || 'https://journoid.app',
+    file,
+    fetcher = fetch,
+    now = Date.now,
+    wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  } = {}) {
+    this.origin = secureUrl(origin).origin
+    this.file =
+      file ??
+      join(
+        process.env.XDG_CONFIG_HOME || join(homedir(), '.config'),
+        'journoid',
+        'credentials.json'
+      )
+    this.fetcher = fetcher
+    this.now = now
+    this.wait = wait
+  }
+
+  async readStore() {
+    try {
+      const value = JSON.parse(await readFile(this.file, 'utf8'))
+      if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Invalid credentials file. Run journoid login again.')
+      return value
+    } catch (error) {
+      if (error.code === 'ENOENT') return {}
+      throw error
+    }
+  }
+
+  async save(account, options = {}) {
+    await mkdir(dirname(this.file), { recursive: true, mode: 0o700 })
+    await chmod(dirname(this.file), 0o700)
+    // Rename keeps readers safe; the lock also serializes read-check-write
+    // transactions across CLI processes, including different server origins.
+    const release = await lockfile.lock(this.file, {
+      realpath: false,
+      retries: { retries: 30, minTimeout: 25, maxTimeout: 500 },
+    })
+    try {
+      const store = await this.readStore()
+      if (
+        Object.hasOwn(options, 'expected') &&
+        JSON.stringify(store[this.origin]) !== JSON.stringify(options.expected)
+      )
+        throw new Error('Your CLI session changed. Run the command again.')
+      if (account) store[this.origin] = account
+      else delete store[this.origin]
+      const temporary = `${this.file}.${randomUUID()}.tmp`
+      try {
+        await writeFile(temporary, JSON.stringify(store), {
+          flag: 'wx',
+          mode: 0o600,
+        })
+        await rename(temporary, this.file)
+      } finally {
+        await unlink(temporary).catch((error) => {
+          if (error.code !== 'ENOENT') throw error
+        })
+      }
+    } finally {
+      await release()
+    }
+  }
+
+  async json(url, options = {}, { ignoreBody = false } = {}) {
+    const response = await this.fetcher(secureUrl(url), {
+      ...options,
+      redirect: 'error',
+      signal: AbortSignal.timeout(30_000),
+    })
+    // Revocation is status-only. Data and token responses must be readable JSON.
+    if (ignoreBody) {
+      if (response.body) await response.body.cancel().catch(() => {})
+      return { response }
+    }
+    const value = await response.json()
+    return { response, value }
+  }
+
+  async discover() {
+    const { response, value } = await this.json(
+      `${this.origin}/.well-known/journoid`
+    )
+    if (
+      !response.ok ||
+      !value.configured ||
+      typeof value.clientId !== 'string' ||
+      !value.clientId ||
+      typeof value.authorizationServer !== 'string' ||
+      value.resource !== `${this.origin}/mcp` ||
+      !Array.isArray(value.scopes) ||
+      !value.scopes.every((scope) => typeof scope === 'string') ||
+      !value.scopes.includes('journoid:full')
+    )
+      throw new Error(
+        'CLI sign-in is not configured on this Journoid server yet.'
+      )
+    const issuer = secureUrl(value.authorizationServer).origin
+    const metadata = await this.json(
+      `${issuer}/.well-known/oauth-authorization-server`
+    )
+    if (
+      !metadata.response.ok ||
+      metadata.value.issuer !== issuer ||
+      !metadata.value.device_authorization_endpoint ||
+      !metadata.value.token_endpoint ||
+      !metadata.value.revocation_endpoint
+    )
+      throw new Error('This server does not support device sign-in.')
+    const endpoints = metadata.value
+    for (const key of [
+      'device_authorization_endpoint',
+      'token_endpoint',
+      'revocation_endpoint',
+    ]) {
+      if (endpoints[key] && secureUrl(endpoints[key]).origin !== issuer)
+        throw new Error(
+          'The authorization server returned an unexpected endpoint.'
+        )
+    }
+    return {
+      clientId: value.clientId,
+      issuer,
+      endpoints,
+      scopes: value.scopes,
+      resource: value.resource,
+    }
+  }
+
+  async form(url, values, options) {
+    return this.json(
+      url,
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams(values),
+      },
+      options
+    )
+  }
+
+  accountFromTokens(tokens, config, previous) {
+    if (
+      typeof tokens.access_token !== 'string' ||
+      !Number.isFinite(tokens.expires_in) ||
+      tokens.expires_in <= 0
+    )
+      throw new Error('The sign-in server returned an invalid token response.')
+    return {
+      accessToken: tokens.access_token,
+      refreshToken: tokens.refresh_token ?? previous?.refreshToken,
+      expiresAt: this.now() + tokens.expires_in * 1000,
+      clientId: config.clientId,
+      tokenEndpoint: config.endpoints.token_endpoint,
+      revocationEndpoint: config.endpoints.revocation_endpoint,
+      resource: config.resource ?? previous?.resource,
+    }
+  }
+
+  async login(onDevice) {
+    const config = await this.discover()
+    const { response, value } = await this.form(
+      config.endpoints.device_authorization_endpoint,
+      {
+        client_id: config.clientId,
+        scope: config.scopes.join(' '),
+        ...(config.resource ? { resource: config.resource } : {}),
+      }
+    )
+    if (
+      !response.ok ||
+      typeof value.device_code !== 'string' ||
+      typeof value.user_code !== 'string' ||
+      !Number.isFinite(value.expires_in) ||
+      value.expires_in <= 0
+    )
+      throw new Error('Could not start sign-in. Try again.')
+    const verificationUrl = secureUrl(
+      value.verification_uri_complete || value.verification_uri
+    ).href
+    onDevice({ url: verificationUrl, code: value.user_code })
+    const expires = this.now() + value.expires_in * 1000
+    let interval = Math.max(5, Number(value.interval) || 5) * 1000
+    while (this.now() < expires) {
+      await this.wait(Math.min(interval, expires - this.now()))
+      if (this.now() >= expires) break
+      const token = await this.form(config.endpoints.token_endpoint, {
+        grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+        client_id: config.clientId,
+        device_code: value.device_code,
+        ...(config.resource ? { resource: config.resource } : {}),
+      })
+      if (token.response.ok && token.value.access_token) {
+        await this.save(this.accountFromTokens(token.value, config))
+        // Verify scope, audience, and connection access before reporting success.
+        // A device token without an audience gets one resource-bound refresh.
+        return this.request('GET')
+      }
+      if (token.value.error === 'authorization_pending') continue
+      if (token.value.error === 'slow_down') {
+        interval += 5000
+        continue
+      }
+      if (token.value.error === 'access_denied')
+        throw new Error('Sign-in was declined.')
+      if (token.value.error === 'expired_token') break
+      throw new Error('Sign-in failed. Run journoid login again.')
+    }
+    throw new Error('The sign-in code expired. Run journoid login again.')
+  }
+
+  async refresh(account) {
+    if (!account.refreshToken)
+      throw new Error('Sign in again with journoid login.')
+    const { response, value } = await this.form(account.tokenEndpoint, {
+      grant_type: 'refresh_token',
+      client_id: account.clientId,
+      refresh_token: account.refreshToken,
+      ...(account.resource ? { resource: account.resource } : {}),
+    })
+    if (!response.ok)
+      throw new Error('Your session expired. Run journoid login again.')
+    const updated = this.accountFromTokens(
+      value,
+      {
+        clientId: account.clientId,
+        endpoints: {
+          token_endpoint: account.tokenEndpoint,
+          revocation_endpoint: account.revocationEndpoint,
+        },
+      },
+      account
+    )
+    await this.save(updated, { expected: account })
+    return updated
+  }
+
+  async request(method, { view, body } = {}) {
+    let account = (await this.readStore())[this.origin]
+    if (!account?.accessToken)
+      throw new Error('Sign in first with journoid login.')
+    if (account.expiresAt <= this.now() + 30_000)
+      account = await this.refresh(account)
+    const url = new URL('/api/agents', this.origin)
+    if (view) url.searchParams.set('view', view)
+    const send = async () => {
+      try {
+        return await this.json(url, {
+          method,
+          headers: {
+            Authorization: `Bearer ${account.accessToken}`,
+            'Content-Type': 'application/json',
+          },
+          ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        })
+      } catch {
+        throw new Error(
+          method === 'POST'
+            ? 'Connection lost. Check Journoid before retrying this change; it may have completed.'
+            : 'Could not reach Journoid. Try again.'
+        )
+      }
+    }
+    let result = await send()
+    if (result.response.status === 401) {
+      account = await this.refresh(account)
+      result = await send()
+    }
+    if (!result.response.ok)
+      throw new Error(
+        typeof result.value.error === 'string'
+          ? result.value.error
+          : `Journoid returned ${result.response.status}.`
+      )
+    return result.value
+  }
+
+  async logout() {
+    const account = (await this.readStore())[this.origin]
+    if (account?.refreshToken) {
+      if (!account.revocationEndpoint)
+        throw new Error(
+          'Disconnect the CLI in Journoid Settings before removing these credentials.'
+        )
+      const { response } = await this.form(
+        account.revocationEndpoint,
+        {
+          token: account.refreshToken,
+          token_type_hint: 'refresh_token',
+          client_id: account.clientId,
+        },
+        { ignoreBody: true }
+      )
+      if (!response.ok)
+        throw new Error(
+          'Could not revoke the session. Try again, or disconnect the CLI in Journoid Settings.'
+        )
+    }
+    await this.save(undefined, { expected: account })
+  }
+}
+
+const help = `Journoid CLI
+
+  journoid login [--no-browser]
+  journoid status
+  journoid blocks
+  journoid actions [action]
+  journoid call <action> --input '<JSON>'
+  journoid call <action> --input-file <path|->
+  journoid logout
+
+Data commands print JSON. --json is accepted for agent scripts.
+Use --url <origin> to select another server. Full access includes deletion.
+Writes are not automatically retried after a lost response.
+`
+
+export async function main(args = process.argv.slice(2)) {
+  const take = (flag) => {
+    const index = args.indexOf(flag)
+    if (index < 0) return undefined
+    const value = args[index + 1]
+    if (!value || value.startsWith('--'))
+      throw new Error(`Missing value for ${flag}.`)
+    args.splice(index, 2)
+    return value
+  }
+  const origin = take('--url')
+  const inputText = take('--input')
+  const inputFile = take('--input-file')
+  const noBrowser = args.includes('--no-browser')
+  args = args.filter((arg) => !['--json', '--no-browser'].includes(arg))
+  const [command, action, ...rest] = args
+  if (!command || ['help', '--help', '-h'].includes(command)) {
+    console.log(help)
+    return
+  }
+  if (
+    rest.length ||
+    args.some((arg) => arg.startsWith('--')) ||
+    (action !== undefined && !['actions', 'call'].includes(command)) ||
+    (noBrowser && command !== 'login') ||
+    ((inputText !== undefined || inputFile !== undefined) && command !== 'call')
+  )
+    throw new Error('Unknown argument. Run journoid --help.')
+  const client = new JournoidClient({ origin })
+  let result
+  if (command === 'login') {
+    result = await client.login(({ url, code }) => {
+      console.error(`Open ${url}\nYour code: ${code}`)
+      if (!noBrowser) {
+        const program =
+          process.platform === 'darwin'
+            ? 'open'
+            : process.platform === 'win32'
+              ? 'rundll32'
+              : 'xdg-open'
+        const browserArgs =
+          process.platform === 'win32'
+            ? ['url.dll,FileProtocolHandler', url]
+            : [url]
+        const browser = spawn(program, browserArgs, { stdio: 'ignore' })
+        browser.on('error', () => {})
+        browser.unref()
+      }
+    })
+  } else if (command === 'logout') {
+    await client.logout()
+    result = { signedOut: true }
+  } else if (command === 'status') result = await client.request('GET')
+  else if (command === 'blocks')
+    result = await client.request('GET', { view: 'blocks' })
+  else if (command === 'actions') {
+    const actions = await client.request('GET', { view: 'actions' })
+    result = action ? actions.find((item) => item.name === action) : actions
+    if (!result) throw new Error('Unknown action. Run journoid actions.')
+  } else if (command === 'call') {
+    if (!action) throw new Error('Choose an action. Run journoid actions.')
+    if (inputText !== undefined && inputFile !== undefined)
+      throw new Error('Choose --input or --input-file.')
+    let text = inputText ?? '{}'
+    if (inputFile === '-') {
+      const chunks = []
+      let size = 0
+      for await (const chunk of process.stdin) {
+        size += Buffer.byteLength(chunk)
+        if (size > 60_000) throw new Error('Action input is too large.')
+        chunks.push(Buffer.from(chunk))
+      }
+      text = Buffer.concat(chunks).toString('utf8')
+    } else if (inputFile !== undefined) text = await readFile(inputFile, 'utf8')
+    if (Buffer.byteLength(text) > 60_000)
+      throw new Error('Action input is too large.')
+    const input = JSON.parse(text)
+    if (!input || typeof input !== 'object' || Array.isArray(input))
+      throw new Error('Input must be a JSON object.')
+    result = await client.request('POST', { body: { action, input } })
+  } else throw new Error('Unknown command. Run journoid --help.')
+  console.log(JSON.stringify(result, null, 2))
+  if (result && typeof result === 'object' && result.success === false)
+    process.exitCode = 1
+}
+
+// npm exposes the executable through a symlink on Unix.
+const entryFile = process.argv[1]
+  ? await realpath(process.argv[1]).catch(() => undefined)
+  : undefined
+if (entryFile && import.meta.url === pathToFileURL(entryFile).href) {
+  main().catch((error) => {
+    console.error(error.message)
+    process.exitCode = 1
+  })
+}

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@journoid/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Connect your agents and terminal to Journoid",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.14.0"
+  },
+  "bin": {
+    "journoid": "./bin/journoid.mjs"
+  },
+  "files": [
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/expl0r3rgu1/journoid.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://journoid.app",
+  "dependencies": {
+    "proper-lockfile": "4.1.2"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  }
 }