@awiki/cli 0.0.1-beta.2

package/scripts/release/withdraw-release.sh

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+cd "${ROOT_DIR}"
+
+VERSION="${1:-}"
+
+if [ -z "${VERSION}" ]; then
+  echo "Usage: scripts/release/withdraw-release.sh <version>" >&2
+  echo "Example: scripts/release/withdraw-release.sh 0.1.0" >&2
+  echo "         scripts/release/withdraw-release.sh 0.2.0-beta.1" >&2
+  exit 1
+fi
+
+TAG="v${VERSION}"
+EXECUTE="${AWIKI_CLI_WITHDRAW_EXECUTE:-0}"
+
+echo "Preparing to withdraw awiki-cli version ${VERSION} (tag ${TAG})."
+echo
+
+if ! git rev-parse -q --verify "refs/tags/${TAG}" >/dev/null; then
+  echo "Warning: local tag ${TAG} does not exist." >&2
+else
+  echo "Local tag ${TAG} exists."
+fi
+
+if git ls-remote --tags origin "refs/tags/${TAG}" | grep -q .; then
+  echo "Remote tag ${TAG} exists on origin."
+else
+  echo "Warning: remote tag ${TAG} does not exist on origin." >&2
+fi
+
+echo
+echo "Recommended rollback actions:"
+echo
+echo "1) Delete Git tag (local + origin):"
+echo "   git tag -d ${TAG} || true"
+echo "   git push origin :refs/tags/${TAG} || true"
+echo
+echo "2) Adjust GitHub Release (requires GitHub CLI 'gh'):"
+echo "   gh release delete ${TAG} --yes || true"
+echo
+echo "3) Adjust npm registry state for @awiki/cli@${VERSION}:"
+echo "   # Option A: mark deprecated but keep the version:"
+echo "   npm deprecate @awiki/cli@${VERSION} \"Deprecated due to bad release; please upgrade.\""
+echo
+echo "   # Option B: move dist-tags away from the bad version (if applicable):"
+echo "   # npm dist-tag add @awiki/cli@<good-version> latest"
+echo "   # npm dist-tag rm @awiki/cli@${VERSION} latest"
+echo
+echo "   # Option C: unpublish (only for very new versions; may be restricted by npm policy):"
+echo "   # npm unpublish @awiki/cli@${VERSION}"
+echo
+
+if [ "${EXECUTE}" != "1" ]; then
+  echo "AWIKI_CLI_WITHDRAW_EXECUTE is not set to 1; no destructive actions will be executed."
+  echo "Review the above commands carefully, then re-run with:"
+  echo
+  echo "  AWIKI_CLI_WITHDRAW_EXECUTE=1 scripts/release/withdraw-release.sh ${VERSION}"
+  echo
+  exit 0
+fi
+
+echo "AWIKI_CLI_WITHDRAW_EXECUTE=1 set; executing rollback commands..."
+
+set +e
+
+git tag -d "${TAG}" 2>/dev/null || true
+git push origin ":refs/tags/${TAG}" || true
+
+if command -v gh >/dev/null 2>&1; then
+  gh release delete "${TAG}" --yes || true
+else
+  echo "Warning: GitHub CLI 'gh' not found; skipping GitHub Release deletion." >&2
+fi
+
+echo "Rollback commands executed. You may still need to run npm deprecate/dist-tag commands manually as appropriate."

package/scripts/run.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+
+function findBinary() {
+  const rootDir = path.resolve(__dirname, '..');
+  const binDir = path.join(rootDir, 'bin');
+  const exeName = process.platform === 'win32' ? 'awiki-cli.exe' : 'awiki-cli';
+  return path.join(binDir, exeName);
+}
+
+function fileExists(p) {
+  try {
+    fs.accessSync(p, fs.constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function getPackageVersion() {
+  try {
+    const pkg = require(path.resolve(__dirname, '..', 'package.json'));
+    return typeof pkg.version === 'string' ? pkg.version : 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+function run() {
+  const binPath = findBinary();
+
+  if (!fileExists(binPath)) {
+    const version = getPackageVersion();
+    console.error(`[awiki-cli] Binary not found at ${binPath}.`);
+    console.error('[awiki-cli] Please download it first, for example:');
+    console.error('  npm run install-binary');
+    console.error('');
+    console.error('If you installed this package globally, you may need to run the command with the same package manager (npm/pnpm/yarn).');
+    console.error(`Current package version: ${version}`);
+    process.exit(1);
+  }
+
+  const args = process.argv.slice(2);
+  const child = spawn(binPath, args, { stdio: 'inherit' });
+
+  child.on('exit', code => {
+    process.exit(code ?? 1);
+  });
+
+  child.on('error', err => {
+    console.error(`[awiki-cli] Failed to start binary: ${err.message}`);
+    process.exit(1);
+  });
+}
+
+if (require.main === module) {
+  run();
+}
+
+module.exports = {
+  _internal: {
+    findBinary,
+    fileExists,
+  },
+};

package/skills/README.md

@@ -0,0 +1,32 @@
+# awiki Skills
+
+This directory contains the awiki skill set for the current `awiki-cli` product surface.
+
+## Structure
+
+- `awiki-bundle/`: routing entrypoint
+- `awiki-shared/`: shared rules and safety boundaries
+- `awiki-*/`: domain, workflow, and debug skills
+- `manifests/skills.yaml`: structured skill index
+- `templates/`: authoring templates for future skills
+
+## Current Source of Truth
+
+Skill maintenance currently follows two coordinated sources:
+
+1. `internal/cmdmeta/catalog.go` for command contract and implementation status
+2. `skills/manifests/skills.yaml` for skill routing, grouping, and ownership
+
+If they disagree:
+
+- command existence and implementation status come from `cmdmeta`
+- skill ownership and routing come from `skills.yaml`
+
+## Maintenance Rules
+
+- Use `awiki-cli` in command examples
+- Keep shared rules in `awiki-shared` only
+- Mark unimplemented capabilities as `partial` or `planned`
+- Prefer canonical commands over shortcuts or imagined aliases
+- Route multi-step tasks through workflow skills
+- Use debug only as a last resort

package/skills/awiki-bundle/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: awiki-bundle
+version: 2.0.0
+description: Route awiki-cli tasks to the correct shared, domain, workflow, or debug skill.
+allowed-tools:
+  - Read
+  - Bash(awiki-cli:*)
+metadata:
+  type: bundle
+  current_binary: awiki-cli
+  implemented_status: implemented
+  depends_on:
+    - awiki-shared
+  covered_commands:
+    - status
+    - docs
+    - schema
+    - doctor
+    - config.show
+    - version
+    - completion
+---
+
+# awiki Bundle Skill
+
+CRITICAL — Read `../awiki-shared/SKILL.md` before loading any other awiki skill.
+
+## Use This Skill For
+
+- selecting the correct awiki skill for the task
+- discovering the current product surface
+- deciding whether the task needs a domain skill, workflow skill, or debug fallback
+
+## Product Surface
+
+Use these commands before domain routing when you need context or validation:
+
+- `awiki-cli status`
+- `awiki-cli docs [topic]`
+- `awiki-cli schema [command]`
+- `awiki-cli doctor`
+- `awiki-cli config show`
+- `awiki-cli version`
+- `awiki-cli completion <bash|zsh|fish|powershell>`
+
+## Routing
+
+- identity, DID, handle, bind, recover, profile, import-v1 -> `../awiki-id/SKILL.md`
+- direct message, group send, inbox, history, read state, secure-message contract -> `../awiki-msg/SKILL.md`
+- group lifecycle, membership, policy, group state -> `../awiki-group/SKILL.md`
+- runtime mode, websocket listener, daemon bridge, heartbeat contract -> `../awiki-runtime/SKILL.md`
+- content pages, slug lifecycle, markdown publishing -> `../awiki-page/SKILL.md`
+- people, followers, following, local contacts -> `../awiki-people/SKILL.md`
+- first-time setup, migration, registration, runtime bootstrap -> `../awiki-workflow-onboarding/SKILL.md`
+- group review, relationship discovery, intro drafting -> `../awiki-workflow-discovery/SKILL.md`
+- local SQLite, raw RPC, schema cache, logs -> `../awiki-debug/SKILL.md`
+
+## Routing Order
+
+1. Read shared rules.
+2. Prefer canonical commands in the matching domain skill.
+3. Use a workflow skill for multi-step tasks.
+4. Use debug only when canonical commands or workflows do not cover the need.
+
+## Important Notes
+
+- The current public binary is `awiki-cli`.
+- `group` is a first-class domain and is not folded into `msg`.
+- `people`, `msg secure`, `runtime heartbeat`, and several debug helpers are still partial or planned. Check the target skill before promising support.
+- If the command shape is unclear, inspect `awiki-cli schema [command]` before improvising.
+
+## Command Discovery
+
+- `awiki-cli --help`
+- `awiki-cli schema`
+- `awiki-cli <domain> --help`

package/skills/awiki-debug/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: awiki-debug
+version: 2.0.0
+description: Debugging helpers for local SQLite, raw RPC, schema cache, and logs.
+allowed-tools:
+  - Read
+  - Bash(awiki-cli:*)
+metadata:
+  type: debug
+  current_binary: awiki-cli
+  implemented_status: partial
+  depends_on:
+    - awiki-shared
+  covered_commands:
+    - debug.db.query
+    - debug.db.import-v1
+  planned_commands:
+    - debug.raw.rpc
+    - debug.schema-cache
+    - debug.logs
+---
+
+# awiki Debug Skill
+
+CRITICAL — Read `../awiki-shared/SKILL.md` first.
+
+## When to Use
+
+Use debug only after these paths are insufficient:
+
+1. `awiki-cli status`
+2. `awiki-cli docs [topic]`
+3. `awiki-cli schema [command]`
+4. `awiki-cli doctor`
+5. `awiki-cli config show`
+6. the matching domain or workflow skill
+
+## Currently Available Commands
+
+- `awiki-cli debug db query "<SQL>"`
+- `awiki-cli debug db import-v1 [--path <legacy_dir>]`
+
+## Planned but Not Implemented Yet
+
+- `awiki-cli debug raw rpc`
+- `awiki-cli debug schema-cache`
+- `awiki-cli debug logs [--follow]`
+
+## Safe-First Decision Tree
+
+- if the problem is command shape or flags -> use `schema`
+- if the problem is environment, config, or store state -> use `doctor`
+- if the problem is active identity or runtime mode -> use `config show`
+- only use `debug db query` for read-only or narrowly scoped inspection
+- only use `debug db import-v1` after a dry run and explicit user confirmation
+
+## Restrictions
+
+- do not run destructive SQL
+- do not assume raw RPC exists before the command is implemented
+- do not expose JWTs, private keys, secure session material, or unrelated local files
+- do not use debug to bypass domain-level confirmation rules
+
+## Side Effects and Confirmation
+
+| Command family | Effect | Confirmation rule |
+|---|---|---|
+| `debug db query` | local database inspection | safe for narrow non-destructive reads |
+| `debug db import-v1` | local database mutation and migration import | explicit confirmation and dry run first |
+
+## Recovery Pattern
+
+1. inspect with `debug db query`
+2. translate the finding back into canonical runtime, identity, or message behavior
+3. return to the domain skill and avoid staying in debug longer than necessary
+
+## References
+
+- `docs/architecture/awiki-skill-architecture.md`
+- `docs/plan/phase-0/implementation-constraints.md`

package/skills/awiki-group/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: awiki-group
+version: 2.0.0
+description: Group lifecycle, membership updates, policy changes, and group state inspection.
+allowed-tools:
+  - Read
+  - Bash(awiki-cli:*)
+metadata:
+  type: domain
+  current_binary: awiki-cli
+  implemented_status: implemented
+  depends_on:
+    - awiki-shared
+  covered_commands:
+    - group.create
+    - group.get
+    - group.join
+    - group.add
+    - group.remove
+    - group.leave
+    - group.update
+    - group.members
+    - group.messages
+---
+
+# awiki Group Skill
+
+CRITICAL — Read `../awiki-shared/SKILL.md` first.
+
+## Use This Skill For
+
+- creating a group
+- joining or leaving a group
+- adding or removing members
+- updating group profile or policy fields
+- inspecting members or group messages
+
+## Core Concepts
+
+- **group**: first-class resource with its own DID and policy
+- **membership**: who is in the group and with what role
+- **discoverability**: visibility and discovery policy
+- **admission mode**: how members enter the group
+- **group messages**: read path for group content; sending still uses `msg send --group`
+
+## Resource Model
+
+- `Identity -> Group -> Members`
+- `Group -> Policy Fields`
+- `Group -> Group Messages`
+
+## Decision Rules
+
+- need to create a group -> `group create`
+- need to inspect metadata or policy -> `group get`
+- need to join an existing open group -> `group join`
+- need to add or remove one member -> `group add` / `group remove`
+- need to change name, description, or policy -> `group update`
+- need to send text into the group -> route to `../awiki-msg/SKILL.md`
+
+## Canonical Commands
+
+- `awiki-cli group create --name "Agent War Room" [...]`
+- `awiki-cli group get --group <group_did>`
+- `awiki-cli group join --group <group_did> [--reason "..."]`
+- `awiki-cli group add --group <group_did> --member <did|handle> [--role ...] [--reason "..."]`
+- `awiki-cli group remove --group <group_did> --member <did|handle> [--reason "..."]`
+- `awiki-cli group leave --group <group_did>`
+- `awiki-cli group update --group <group_did> [--name ...] [--description ...] [...]`
+- `awiki-cli group members --group <group_did> [--limit <n>]`
+- `awiki-cli group messages --group <group_did> [--limit <n>] [--cursor <cursor>]`
+
+## Common Patterns
+
+### Create with dry run first
+
+1. `awiki-cli group create --name "Agent War Room" --dry-run`
+2. `awiki-cli group create --name "Agent War Room"`
+
+### Review before membership mutation
+
+1. `awiki-cli group get --group <group_did>`
+2. `awiki-cli group members --group <group_did>`
+3. `awiki-cli group add --group <group_did> --member <did> --dry-run`
+4. `awiki-cli group add --group <group_did> --member <did>`
+
+## Side Effects and Confirmation
+
+| Command family | Effect | Confirmation rule |
+|---|---|---|
+| `group create` | creates a new group resource | explicit confirmation |
+| `group join` | mutates membership state | explicit confirmation |
+| `group add` / `group remove` | mutates membership state | explicit confirmation |
+| `group leave` | removes the active identity from membership | explicit confirmation |
+| `group update` | mutates group metadata or policy | explicit confirmation |
+
+## Error Handling
+
+- missing or malformed group identifier -> inspect `awiki-cli schema group <subcommand>`
+- access or role issue -> inspect `group get` and `group members` first
+- transport or auth issue -> route to runtime or identity skill as needed
+
+## Implementation Notes
+
+- `group` is a standalone domain in the current repo.
+- `group messages` is read-only inspection; sending remains in `msg send --group`.
+
+## References
+
+- `docs/architecture/awiki-v2-architecture.md`
+- `docs/architecture/awiki-command-v2.md`

package/skills/awiki-id/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: awiki-id
+version: 2.0.0
+description: DID, handle, contact binding, recovery, identity switching, and profile management.
+allowed-tools:
+  - Read
+  - Bash(awiki-cli:*)
+metadata:
+  type: domain
+  current_binary: awiki-cli
+  implemented_status: implemented
+  depends_on:
+    - awiki-shared
+  covered_commands:
+    - id.status
+    - id.list
+    - id.current
+    - id.use
+    - id.register
+    - id.bind
+    - id.resolve
+    - id.recover
+    - id.profile.get
+    - id.profile.set
+    - id.import-v1
+  hidden_commands:
+    - id.create
+---
+
+# awiki Identity Skill
+
+CRITICAL — Read `../awiki-shared/SKILL.md` first.
+
+## Use This Skill For
+
+- creating or importing a local identity
+- registering or recovering a handle-backed identity
+- binding phone or email contact information
+- switching the default identity
+- reading or updating the DID profile
+
+## Core Concepts
+
+- **identity**: the local awiki identity container selected with `--identity`
+- **DID**: the protocol identifier used by the services
+- **handle**: the human-friendly public identifier
+- **contact binding**: adding phone or email to an existing identity
+- **current identity**: the default local identity used when `--identity` is omitted
+
+## Lifecycle
+
+`status -> create/register/import -> bind -> profile set -> current/use`
+
+## Decision Rules
+
+- no local identity yet -> prefer `awiki-cli id register ...`; use hidden `id create` only for bootstrap, migration, or debug
+- local identity exists but no handle-backed user state -> `awiki-cli id register ...`
+- handle exists but contact info is incomplete -> `awiki-cli id bind ...`
+- lost handle but still have recovery phone -> `awiki-cli id recover ...`
+- need to inspect multiple local identities -> `awiki-cli id list`
+- need to switch the default identity -> `awiki-cli id use <identity>`
+- need to inspect public profile data -> `awiki-cli id profile get ...`
+
+## Canonical Commands
+
+- `awiki-cli id status`
+- `awiki-cli id list`
+- `awiki-cli id current`
+- `awiki-cli id use <identity>`
+- `awiki-cli id register --handle <handle> (--phone <phone> [--otp <code>] | --email <email> [--wait])`
+- `awiki-cli id bind (--phone <phone> [--otp <code>] | --email <email> [--wait])`
+- `awiki-cli id resolve (--handle <handle> | --did <did>)`
+- `awiki-cli id recover --handle <handle> --phone <phone> --otp <code>`
+- `awiki-cli id profile get [--self | --handle <handle> | --did <did>]`
+- `awiki-cli id profile set [--display-name ...] [--bio ...] [--tags ...] [--markdown ...] [--markdown-file ...]`
+- `awiki-cli id import-v1 [--name <identity> | --all]`
+
+## Common Patterns
+
+### Preferred registration flow
+
+1. `awiki-cli id status`
+2. `awiki-cli id register --handle alice --phone +8613800138000 --otp 123456`
+3. `awiki-cli id current`
+4. `awiki-cli id bind --email alice@example.com --wait`
+5. `awiki-cli id profile set --display-name "Alice"`
+
+### Import from v1 before switching
+
+1. `awiki-cli id import-v1 --all --dry-run`
+2. `awiki-cli id import-v1 --all`
+3. `awiki-cli id list`
+4. `awiki-cli id use <identity>`
+
+## Side Effects and Confirmation
+
+| Command family | Effect | Confirmation rule |
+|---|---|---|
+| `id register` | creates or completes remote user registration | explicit confirmation |
+| `id bind` | mutates remote identity contact data | explicit confirmation |
+| `id recover` | rebinds a handle using recovery flow | explicit confirmation |
+| `id use` | changes local default identity | explicit confirmation |
+| `id profile set` | mutates remote DID profile | explicit confirmation |
+| `id import-v1` | imports local credentials and metadata | explicit confirmation |
+| `id create` | creates local DID material only | explicit confirmation and only for internal/bootstrap use |
+
+## Error Handling
+
+- registration or bind shape confusion -> inspect `awiki-cli schema id register` or `awiki-cli schema id bind`
+- auth or token confusion -> recover or re-register the identity
+- missing identity -> use `awiki-cli id list` and `awiki-cli id current`
+- local store confusion -> use `awiki-cli doctor`
+
+## Implementation Notes
+
+- `id create` is hidden on purpose.
+- Public guidance must stay handle-first.
+- `user_id` is not part of the public contract for this skill.
+
+## References
+
+- `docs/architecture/awiki-v2-architecture.md`
+- `docs/architecture/awiki-command-v2.md`