← Commit history
._LICENSEadded
⋯ 1 unchanged line ⋯
._README.mdadded
⋯ 1 unchanged line ⋯
._VERSIONadded
⋯ 1 unchanged line ⋯
._install.shadded
⋯ 1 unchanged line ⋯
._page.jsonadded
⋯ 1 unchanged line ⋯
._uninstall.shadded
⋯ 1 unchanged line ⋯
LICENSEadded+21
@@ -0,0 +1,21 @@+MIT License++Copyright (c) 2026 Adom Industries Inc.++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.
VERSIONadded+1
@@ -0,0 +1 @@+0.1.0
bin/._adom-forumadded
⋯ 1 unchanged line ⋯
bin/adom-forumadded+295
@@ -0,0 +1,295 @@+#!/usr/bin/env node+// adom-forum — post to and read the Adom Forum from a container or a laptop.+//+// Auth: a Carbon session token. Resolution order mirrors adom-wiki:+//   ADOM_FORUM_TOKEN → /var/run/adom/api-key → /run/adom/api-key → ~/.config/adom-forum/token+// The token is only ever sent to *.adom.inc, *.adom.internal, or a loopback host.+//+// Every write goes through the forum's Bearer API, which records it as posted+// through an agent and shows a "via <agent>" badge next to the author. Pass+// --agent "Codex Astra" (or set ADOM_AGENT_NAME) so the badge names the tool.+//+// Consent: `thread create` and `reply` print a preview and exit 2 unless+// --permission-to-post-given is passed. Show the user the preview first.++import { readFileSync, existsSync, statSync } from 'node:fs'+import { basename, dirname, resolve as resolvePath, extname } from 'node:path'+import { homedir } from 'node:os'+import { createHash } from 'node:crypto'++const VERSION = '0.1.0'++// The CLI runs in the shared Linux runtime behind Hydrogen web, macOS, and+// Windows alike. It depends only on Node 18+ (global fetch, FormData, Blob)+// and the container token file; nothing here touches the host OS.+const NODE_MAJOR = Number(process.versions.node.split('.')[0])+if (NODE_MAJOR < 18) {+  process.stderr.write(`adom-forum: Node 18 or newer is required (found ${process.versions.node})\n`)+  process.exit(1)+}+const DEFAULT_URL = 'https://forum.adom.inc'+const HELP = `adom-forum ${VERSION} — Adom Forum from the terminal++USAGE+  adom-forum spaces [--json]+  adom-forum threads [--space <slug>] [--sort hot|new|top] [--limit N] [--json]+  adom-forum thread get <id> [--json]+  adom-forum thread create --space <slug> --title "<title>" --body <text|@file|-> [--agent "<name>"]+                           [--idempotency-key <key>] [--permission-to-post-given] [--json]+  adom-forum reply <thread-id> --body <text|@file|-> [--agent "<name>"] [--idempotency-key <key>]+                           [--permission-to-post-given] [--json]+  adom-forum media upload <file> [--json]+  adom-forum whoami [--json]++BODY+  --body takes Markdown inline, @path/to/file.md, or - for stdin. Local images referenced as+  ![caption](./photo.png) or ![clip](./demo.mp4) are uploaded and rewritten to gated /media/ URLs+  before posting, so images and videos land exactly where they sit in the Markdown.++CONSENT+  Writes preview first and exit 2. Re-run with --permission-to-post-given after the user says yes.++ENV+  FORUM_URL (default ${DEFAULT_URL})   ADOM_FORUM_TOKEN   ADOM_AGENT_NAME+`++function fail(message, code = 1, extra = {}) {+  if (flags.json) process.stdout.write(JSON.stringify({ status: 'error', error: message, ...extra }) + '\n')+  else process.stderr.write(`adom-forum: ${message}\n`)+  process.exit(code)+}++function parseArgs(argv) {+  const positional = []+  const flags = {}+  for (let index = 0; index < argv.length; index += 1) {+    const arg = argv[index]+    if (arg.startsWith('--')) {+      const key = arg.slice(2)+      const next = argv[index + 1]+      if (['json', 'permission-to-post-given', 'help', 'version'].includes(key) || next === undefined || next.startsWith('--')) flags[key] = true+      else { flags[key] = next; index += 1 }+    } else positional.push(arg)+  }+  return { positional, flags }+}++const { positional, flags } = parseArgs(process.argv.slice(2))++function resolveToken() {+  if (process.env.ADOM_FORUM_TOKEN) return { token: process.env.ADOM_FORUM_TOKEN.trim(), source: 'env:ADOM_FORUM_TOKEN' }+  for (const path of ['/var/run/adom/api-key', '/run/adom/api-key', resolvePath(homedir(), '.config/adom-forum/token')]) {+    try {+      const value = readFileSync(path, 'utf8').trim()+      if (value) return { token: value, source: `file:${path}` }+    } catch { /* try the next one */ }+  }+  return { token: null, source: null }+}++function baseUrl() {+  return (process.env.FORUM_URL || DEFAULT_URL).replace(/\/+$/, '')+}++function trustedHost(url) {+  const host = new URL(url).hostname+  return host === 'localhost' || host === '127.0.0.1' || host.endsWith('.adom.inc') || host.endsWith('.adom.internal')+}++async function api(method, path, { body, form, idempotencyKey } = {}) {+  const url = `${baseUrl()}${path}`+  const { token, source } = resolveToken()+  const headers = { 'user-agent': `adom-forum/${VERSION}`, accept: 'application/json' }+  if (token) {+    if (!trustedHost(url)) fail(`refusing to send the Adom token to ${new URL(url).hostname}`)+    headers.authorization = `Bearer ${token}`+  }+  const agent = flags.agent || process.env.ADOM_AGENT_NAME+  if (agent) headers['x-adom-agent'] = String(agent)+  if (idempotencyKey) headers['idempotency-key'] = idempotencyKey+  let payload+  if (form) payload = form+  else if (body !== undefined) { headers['content-type'] = 'application/json'; payload = JSON.stringify(body) }+  const response = await fetch(url, { method, headers, body: payload })+  const text = await response.text()+  let data = null+  try { data = text ? JSON.parse(text) : null } catch { data = { raw: text } }+  if (!response.ok) {+    const message = data?.error || `${response.status} ${response.statusText}`+    const hint = response.status === 401 ? (token ? ` (token from ${source} was rejected)` : ' (no token found; set ADOM_FORUM_TOKEN or run inside an Adom container)') : ''+    fail(`${message}${hint}`, response.status === 429 ? 3 : 1, { code: data?.code, status: response.status, data: data?.data })+  }+  return { data, headers: response.headers }+}++function readBody(value) {+  if (value === undefined || value === true) fail('--body is required (text, @file, or - for stdin)')+  if (value === '-') return { text: readFileSync(0, 'utf8'), dir: process.cwd() }+  if (String(value).startsWith('@')) {+    const path = resolvePath(String(value).slice(1))+    return { text: readFileSync(path, 'utf8'), dir: dirname(path) }+  }+  return { text: String(value), dir: process.cwd() }+}++const IMAGE_TYPES = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp' }+const VIDEO_TYPES = { '.mp4': 'video/mp4', '.webm': 'video/webm', '.mov': 'video/quicktime' }++// Videos go straight to object storage: presign, PUT, confirm. The forum+// never proxies the bytes.+async function uploadVideo(path, type) {+  const size = statSync(path).size+  const { data: ticket } = await api('POST', '/api/media/videos/presign', { body: { filename: basename(path), content_type: type, size } })+  const put = await fetch(ticket.upload_url, { method: ticket.upload_method || 'PUT', headers: { 'content-type': type }, body: readFileSync(path) })+  if (!put.ok) fail(`${basename(path)}: storage rejected the upload (${put.status})`)+  const { data } = await api('POST', '/api/media/videos/confirm', { body: { id: ticket.id } })+  return data+}++async function uploadFile(path) {+  const extension = extname(path).toLowerCase()+  if (VIDEO_TYPES[extension]) return uploadVideo(path, VIDEO_TYPES[extension])+  const type = IMAGE_TYPES[extension]+  if (!type) fail(`${path}: only PNG, JPEG, GIF, WebP images and MP4, WebM, MOV videos can be uploaded`)+  const bytes = readFileSync(path)+  const form = new FormData()+  form.append('file', new Blob([bytes], { type }), basename(path))+  const { data } = await api('POST', '/api/media', { form })+  return data+}++const IMAGE_PATTERN = /!\[([^\]]*)\]\(([^)\s]+)(\s+"[^"]*")?\)/g++function localImagePaths(markdown, dir) {+  const paths = new Set()+  for (const match of markdown.matchAll(IMAGE_PATTERN)) {+    const target = match[2]+    if (/^(https?:)?\/\//i.test(target) || target.startsWith('/media/') || target.startsWith('data:')) continue+    const path = resolvePath(dir, target)+    if (existsSync(path) && statSync(path).isFile()) paths.add(path)+  }+  return [...paths]+}++// Upload local images referenced in the Markdown and rewrite their URLs.+// Only called once the user has approved the post, so a preview never leaves+// orphaned uploads behind.+async function localizeImages(markdown, dir) {+  const pattern = IMAGE_PATTERN+  const uploads = new Map()+  for (const path of localImagePaths(markdown, dir)) {+    if (!uploads.has(path)) {+      const uploaded = await uploadFile(path)+      uploads.set(path, uploaded.url)+      if (!flags.json) process.stderr.write(`   ${VIDEO_TYPES[extname(path).toLowerCase()] ? 'video' : 'image'} → ${uploaded.url} (${basename(path)})\n`)+    }+  }+  const rewritten = markdown.replace(pattern, (whole, alt, target, title = '') => {+    if (/^(https?:)?\/\//i.test(target) || target.startsWith('/media/') || target.startsWith('data:')) return whole+    const path = resolvePath(dir, target)+    return uploads.has(path) ? `![${alt}](${uploads.get(path)}${title})` : whole+  })+  return { markdown: rewritten, uploaded: uploads.size }+}++function preview(kind, fields, markdown) {+  process.stdout.write(`\n──── preview: ${kind} ────\n`)+  for (const [key, value] of Object.entries(fields)) process.stdout.write(`${key}: ${value}\n`)+  process.stdout.write(`\n${markdown.trim()}\n──────────────────────────\n`)+  process.stdout.write(`Not posted. Show this to the user; re-run with --permission-to-post-given once they approve.\n`)+}++function out(value, human) {+  if (flags.json) process.stdout.write(JSON.stringify({ status: 'ok', data: value }) + '\n')+  else process.stdout.write(human)+}++function idempotencyFor(explicit, parts) {+  if (explicit && explicit !== true) return String(explicit)+  return `adom-forum:${createHash('sha256').update(parts.join('')).digest('hex').slice(0, 32)}`+}++async function main() {+  if (flags.version) { process.stdout.write(`adom-forum ${VERSION}\n`); return }+  if (flags.help || positional.length === 0) { process.stdout.write(HELP); return }+  const [command, sub, ...rest] = positional++  if (command === 'whoami') {+    const { token, source } = resolveToken()+    if (!token) fail('no token found; set ADOM_FORUM_TOKEN or run inside an Adom container', 1)+    const { data } = await api('GET', '/api/activity-counts')+    out({ forum: baseUrl(), token_source: source, unread: data }, `forum: ${baseUrl()}\ntoken: ${source}\nunread messages: ${data?.messages ?? 0}, notifications: ${data?.notifications ?? 0}\n`)+    return+  }++  if (command === 'spaces') {+    const { data } = await api('GET', '/api/spaces')+    out(data.spaces, data.spaces.map((space) => `${space.slug.padEnd(16)} ${space.name.padEnd(16)} ${String(space.thread_count).padStart(4)}  ${space.description}`).join('\n') + '\n')+    return+  }++  if (command === 'threads') {+    const params = new URLSearchParams()+    if (flags.space) params.set('space', String(flags.space))+    if (flags.sort) params.set('sort', String(flags.sort))+    if (flags.limit) params.set('limit', String(flags.limit))+    const { data } = await api('GET', `/api/threads?${params}`)+    out(data.threads, data.threads.map((thread) => `${thread.id}  ${String(thread.votes).padStart(3)}▲ ${String(thread.replies).padStart(3)}💬  [${thread.space}] ${thread.title} — ${thread.author.display_name}${thread.agent ? ` via ${thread.agent}` : ''}`).join('\n') + '\n')+    return+  }++  if (command === 'thread' && sub === 'get') {+    const id = rest[0]+    if (!id) fail('thread id required')+    const { data } = await api('GET', `/api/threads/${encodeURIComponent(id)}`)+    const lines = [`# ${data.thread.title}`, `${data.thread.url} · ${data.thread.space} · by ${data.thread.author.display_name}${data.thread.agent ? ` via ${data.thread.agent}` : ''}`, '']+    for (const post of data.posts) lines.push(`--- ${post.opener ? 'opener' : 'reply'} · ${post.author.display_name}${post.agent ? ` via ${post.agent}` : ''} · ${post.created_at}`, post.body ?? '(hidden)', '')+    out(data, lines.join('\n'))+    return+  }++  if (command === 'thread' && sub === 'create') {+    const space = flags.space+    const title = flags.title+    if (!space || space === true) fail('--space is required (see `adom-forum spaces`)')+    if (!title || title === true) fail('--title is required')+    const { text, dir } = readBody(flags.body)+    if (!flags['permission-to-post-given']) {+      preview('new thread', { space, title, agent: flags.agent || process.env.ADOM_AGENT_NAME || '(none)', images_to_upload: localImagePaths(text, dir).map((path) => basename(path)).join(', ') || 'none' }, text)+      process.exit(2)+    }+    // Keyed on the source Markdown so a retry replays even though uploads mint new URLs.+    const key = idempotencyFor(flags['idempotency-key'], ['thread', String(space), String(title), text])+    const { markdown } = await localizeImages(text, dir)+    const { data, headers } = await api('POST', '/api/threads', { body: { space, title, body: markdown }, idempotencyKey: key })+    out({ ...data, replayed: headers.get('idempotent-replayed') === 'true' }, `${headers.get('idempotent-replayed') === 'true' ? 'already posted' : 'posted'}: ${data.url}\n`)+    return+  }++  if (command === 'reply') {+    const id = sub+    if (!id) fail('thread id required')+    const { text, dir } = readBody(flags.body)+    if (!flags['permission-to-post-given']) {+      preview('reply', { thread: id, agent: flags.agent || process.env.ADOM_AGENT_NAME || '(none)', images_to_upload: localImagePaths(text, dir).map((path) => basename(path)).join(', ') || 'none' }, text)+      process.exit(2)+    }+    const key = idempotencyFor(flags['idempotency-key'], ['reply', String(id), text])+    const { markdown } = await localizeImages(text, dir)+    const { data, headers } = await api('POST', `/api/threads/${encodeURIComponent(id)}/posts`, { body: { body: markdown }, idempotencyKey: key })+    out({ ...data, replayed: headers.get('idempotent-replayed') === 'true' }, `${headers.get('idempotent-replayed') === 'true' ? 'already posted' : 'posted'}: ${data.url}\n`)+    return+  }++  if (command === 'media' && sub === 'upload') {+    const path = rest[0]+    if (!path) fail('file path required')+    const data = await uploadFile(resolvePath(path))+    out(data, `${data.url}\n`)+    return+  }++  fail(`unknown command: ${positional.join(' ')}\n\n${HELP}`)+}++main().catch((cause) => fail(cause instanceof Error ? cause.message : String(cause)))
docs/._hero.pngadded
⋯ 1 unchanged line ⋯
docs/hero.pngadded
⋯ 1 unchanged line ⋯
install.shadded+43
@@ -0,0 +1,43 @@+#!/usr/bin/env bash+# adom-forum installer — runs via `adom-wiki pkg install adom/adom-forum`.+#+# The tarball carries the CLI itself (one Node script, no build step) plus the+# skill. Installed by copying real files, no symlinks, so a later uninstall or+# upgrade of the package cannot leave a dangling link behind.+set -euo pipefail+HERE="$(cd "$(dirname "$0")" && pwd)"+BIN_DIR="$HOME/.local/bin"+SKILLS_DIR="$HOME/.claude/skills"+mkdir -p "$BIN_DIR" "$SKILLS_DIR"++# Runs in the shared Linux runtime (Hydrogen web, macOS, and Windows all use+# it). Only Node 18+ is required; no host OS integration is used or assumed.+if ! command -v node >/dev/null 2>&1; then+  echo "[adom-forum] node is required (18 or newer) and was not found on PATH" >&2+  exit 1+fi+NODE_MAJOR="$(node -p 'process.versions.node.split(".")[0]')"+if [ "${NODE_MAJOR:-0}" -lt 18 ]; then+  echo "[adom-forum] node 18 or newer is required (found $(node --version))" >&2+  exit 1+fi++tmp="$BIN_DIR/adom-forum.tmp.$$"+cp "$HERE/bin/adom-forum" "$tmp"+chmod +x "$tmp"+rm -rf "$BIN_DIR/adom-forum"+mv -f "$tmp" "$BIN_DIR/adom-forum"+echo "   bin   → $BIN_DIR/adom-forum"++# adom-wiki 1.0.81+ delivers skills/<name>/SKILL.md itself; older clients need this copy.+rm -rf "$SKILLS_DIR/adom-forum"+mkdir -p "$SKILLS_DIR/adom-forum"+cp "$HERE/skills/adom-forum/SKILL.md" "$SKILLS_DIR/adom-forum/SKILL.md"+echo "   skill → $SKILLS_DIR/adom-forum/SKILL.md"++case ":$PATH:" in+  *":$HOME/.local/bin:"*) ;;+  *) echo "[adom-forum] NOTE: $HOME/.local/bin is not on PATH — add it to your shell rc." ;;+esac++echo "✅ adom-forum $("$BIN_DIR/adom-forum" --version | awk '{print $NF}') installed. Try: adom-forum spaces"
skills/adom-forum/._SKILL.mdadded
⋯ 1 unchanged line ⋯
skills/adom-forum/SKILL.mdadded+78
@@ -0,0 +1,78 @@+---+name: adom-forum+description: Post to and read the Adom Forum (forum.adom.inc) as the user, from the terminal. Use when the user wants to share a build, start a discussion, create a thread for a podcast episode, reply to a forum thread, or see what is new on the forum. Trigger words - forum, adom forum, post to the forum, forum thread, start a thread, reply on the forum, share on the forum, forum.adom.inc.+---++# adom-forum++`adom-forum` posts to the Adom Forum through its machine API using the Adom token every container already has. Posts made this way are attributed to the user **and** marked `via <agent>` on the forum, the way Google Chat shows `(adom-google)` next to messages an AI sent. Always pass the tool you are running as so the badge names it.++```bash+export ADOM_AGENT_NAME="Claude Code"     # or "Codex Astra", "Kimi", …  — shown as "via Claude Code"+```++## The one rule: preview, then permission++`thread create` and `reply` print a preview and **exit 2 without posting** unless `--permission-to-post-given` is passed. Show the user the preview (title, space, body, which images will be uploaded), get an explicit yes, then re-run with the flag. Never post silently. Never add the flag on the first attempt.++## Commands++```bash+adom-forum spaces                                   # slugs: general, questions, show-and-tell, components, …+adom-forum threads [--space show-and-tell] [--sort new] [--limit 20]+adom-forum thread get <id>                          # opener + replies as Markdown+adom-forum thread create --space show-and-tell --title "TMF8829 depth lab build" --body @post.md+adom-forum thread create ... --body @post.md --permission-to-post-given     # after the user approves+adom-forum reply <thread-id> --body "Tested at 5 m, works." --permission-to-post-given+adom-forum media upload ./board-top.png             # prints a /media/... URL+adom-forum whoami+```++Add `--json` to any command for a `{ status, data }` envelope.++## Writing the post++- The body is GitHub-flavored Markdown: headings, bullet points, tables, code, links.+- Put images and videos exactly where they belong with normal image syntax and a **local path**: `![Top side after reflow](./shots/top.png)` or `![Depth demo](./demo.mp4)`. The CLI uploads each local file and rewrites the URL before posting, so the media lands in the flow of the text. Images: PNG, JPEG, GIF, WebP up to 8 MB. Videos: MP4, WebM, MOV up to 256 MB, uploaded straight to storage; they render as an inline player.+- Reference people and wiki pages with `@username` and `@owner/slug`; they render as link chips.+- A thread needs a title of 4 to 160 characters and a body of at least 2 characters.+- Draft long posts to a file and use `--body @file.md` so the preview is readable and the user can edit it.++## Retries and limits++- Posting is idempotent: a retry of the same thread or reply returns the existing one (`already posted`) instead of a duplicate. Pass `--idempotency-key` to control the key.+- Exit code 3 with `Try again in N minutes` means a rate limit. Wait; do not loop.+- New accounts have tighter limits and their posts with external links may be held for review. The post still succeeds and the user sees it; others see it after an admin releases it. Tell the user this if the post does not appear for others right away.+- 403 `Your account cannot post right now` means the account is restricted or banned. Stop and tell the user.++## Auth++Token resolution: `ADOM_FORUM_TOKEN`, then `/var/run/adom/api-key` (every Adom container), then `~/.config/adom-forum/token`. The token is only sent to `*.adom.inc`, `*.adom.internal`, and loopback hosts. `FORUM_URL` points the CLI at staging (`https://fluorine.stg.adom.internal`) or a local dev server.++## Examples++Share a build with photos:++```bash+cat > /tmp/lidar.md <<'EOF'+## What this is+A TMF8829 depth lab board, built end to end by Codex Astra over 13 hours.++![Board, top side](./shots/top.png)++- Forward-mount ToF sensor with a 3D-printed baffle+- USB-C power, ESP32-S3 host+- Bring-up worked first try++![Depth map at 2 m](./shots/depth.png)+EOF+adom-forum thread create --space show-and-tell --title "TMF8829 depth lab board" --body @/tmp/lidar.md+# show the preview, get a yes, then:+adom-forum thread create --space show-and-tell --title "TMF8829 depth lab board" --body @/tmp/lidar.md --permission-to-post-given+```++Podcast episode discussion:++```bash+adom-forum thread create --space general --title "Episode 12: designing for reflow" --body @episode-12.md --agent "Anastasia's AI"+```
uninstall.shadded+6
@@ -0,0 +1,6 @@+#!/usr/bin/env bash+# adom-forum uninstaller — runs via `adom-wiki pkg uninstall adom/adom-forum`.+set -euo pipefail+rm -f "$HOME/.local/bin/adom-forum"+rm -rf "$HOME/.claude/skills/adom-forum"+echo "adom-forum removed"