coherence-cli 0.2.0 → 0.3.0

package/README.md

@@ -1,3 +1,4 @@
+<!-- AUTO-GENERATED from README.template.md. Edit the template, not this file. -->
 # coherence-cli
 
 **Every idea deserves a trail. Every contributor deserves credit.**

package/README.template.md

@@ -0,0 +1,165 @@
+# coherence-cli
+
+**Every idea deserves a trail. Every contributor deserves credit.**
+
+`cc` is the command-line interface for [Coherence Network](https://coherencycoin.com) — an open intelligence platform that traces every idea from inception to payout, with fair attribution, coherence scoring, and federated trust.
+
+```
+npm i -g coherence-cli
+cc status
+```
+
+That's it. You're connected to the live network. No account, no signup, no API key needed for reading.
+
+---
+
+## Why this exists
+
+Most ideas die in the gap between "great thought" and "shipped thing." The people who research, prototype, review, document, and maintain rarely see proportional credit.
+
+Coherence Network changes that. It tracks the full lifecycle:
+
+<!-- include: docs/shared/lifecycle-diagram.md -->
+
+`cc` gives you direct access to all of it from your terminal.
+
+---
+
+## Quick start
+
+### See what's happening
+
+```bash
+cc ideas          # Browse the portfolio ranked by ROI
+cc resonance      # What's alive right now
+cc status         # Network health, node count, your identity
+```
+
+### Go deeper
+
+```bash
+cc idea <id>      # Full scores, open questions, value gaps
+cc specs          # Feature specs with ROI metrics
+cc spec <id>      # Implementation summary, pseudocode, cost
+```
+
+### Contribute
+
+```bash
+cc share          # Submit a new idea (interactive)
+cc stake <id> 10  # Stake 10 CC on an idea you believe in
+cc fork <id>      # Fork an idea and take it a new direction
+cc contribute     # Record any contribution (code, docs, review, design, community)
+```
+
+### Identity — bring your own
+
+Link any identity you already have. No new accounts. 37 providers across 6 categories.
+
+```bash
+cc identity setup                    # Guided onboarding (first time)
+cc identity link github alice-dev    # Link your GitHub
+cc identity link ethereum 0xabc...   # Link your wallet
+cc identity link discord user#1234   # Link Discord
+cc identity                          # See all your linked accounts
+cc identity lookup github alice-dev  # Find anyone by their handle
+```
+
+**Supported providers:**
+
+<!-- include: docs/shared/identity-providers.md -->
+
+You don't need to register anywhere. Just link a provider and start contributing — your work is attributed to your identity across the entire network.
+
+---
+
+## How coherence scoring works
+
+<!-- include: docs/shared/coherence-scoring.md -->
+
+---
+
+## The five pillars
+
+| Pillar | In practice |
+|--------|-------------|
+| **Traceability** | `cc idea <id>` traces from spark to payout. Nothing is lost. |
+| **Trust** | Coherence scores replace subjective judgement with measurable quality. |
+| **Freedom** | Fork any idea. Run your own node. Vote on governance. No gatekeepers. |
+| **Uniqueness** | Every idea, spec, and contribution is uniquely identified and ranked. |
+| **Collaboration** | Multi-contributor attribution with coherence-weighted payouts. Fair by design. |
+
+---
+
+## The Coherence Network ecosystem
+
+Every part of the network links to every other. Jump in wherever makes sense for you.
+
+| Surface | What it is | Link |
+|---------|-----------|------|
+| **Web** | The main site — browse ideas, specs, and contributors visually | [coherencycoin.com](https://coherencycoin.com) |
+| **API** | 100+ endpoints, full OpenAPI docs, the engine behind everything | [api.coherencycoin.com/docs](https://api.coherencycoin.com/docs) |
+| **CLI** | This package — terminal-first access to the full network | [npm: coherence-cli](https://www.npmjs.com/package/coherence-cli) |
+| **MCP Server** | 20 typed tools for AI agents (Claude, Cursor, Windsurf, etc.) | [npm: coherence-mcp-server](https://www.npmjs.com/package/coherence-mcp-server) |
+| **OpenClaw Skill** | Auto-triggers in any OpenClaw instance when you mention ideas, specs, or coherence | [ClawHub: coherence-network](https://clawhub.com/skills/coherence-network) |
+| **GitHub** | Source code, specs, issues, and contribution tracking | [github.com/seeker71/Coherence-Network](https://github.com/seeker71/Coherence-Network) |
+
+---
+
+## Configuration
+
+By default, `cc` talks to the public API at `https://api.coherencycoin.com`. Override with environment variables:
+
+```bash
+# Point to a local node
+export COHERENCE_API_URL=http://localhost:8000
+
+# Enable write operations
+export COHERENCE_API_KEY=your-key
+```
+
+Config is stored in `~/.coherence-network/config.json`.
+
+---
+
+## All commands
+
+```
+cc help                           Show all commands
+cc ideas [limit]                  Browse ideas by ROI
+cc idea <id>                      View idea detail with scores
+cc specs [limit]                  List feature specs
+cc spec <id>                      View spec detail
+cc share                          Submit a new idea
+cc stake <id> <cc>                Stake CC on an idea
+cc fork <id>                      Fork an idea
+cc contribute                     Record any contribution
+cc resonance                      What's alive right now
+cc status                         Network health + node info
+cc identity                       Show linked accounts
+cc identity setup                 Guided identity onboarding
+cc identity link <provider> <id>  Link a provider identity
+cc identity unlink <provider>     Unlink a provider
+cc identity lookup <provider> <id> Find contributor by identity
+```
+
+---
+
+## Get involved
+
+Coherence Network is open source. Every contribution is tracked and attributed — yours will be too.
+
+The simplest way to start:
+
+```bash
+cc ideas            # find something interesting
+cc contribute       # record what you did
+```
+
+Or explore any part of the ecosystem from the table above. Every surface leads to every other.
+
+---
+
+## License
+
+MIT

package/bin/cc.mjs

@@ -7,29 +7,34 @@
  * Zero dependencies. Node 18+ required.
  */
 
-import { listIdeas, showIdea, shareIdea, stakeOnIdea, forkIdea } from "../lib/commands/ideas.mjs";
+import { listIdeas, showIdea, shareIdea, stakeOnIdea, forkIdea, createIdea } from "../lib/commands/ideas.mjs";
 import { listSpecs, showSpec } from "../lib/commands/specs.mjs";
 import { contribute } from "../lib/commands/contribute.mjs";
 import { showStatus, showResonance } from "../lib/commands/status.mjs";
-import { showIdentity, linkIdentity, unlinkIdentity, lookupIdentity, setupIdentity } from "../lib/commands/identity.mjs";
+import { showIdentity, linkIdentity, unlinkIdentity, lookupIdentity, setupIdentity, setIdentity } from "../lib/commands/identity.mjs";
 
 const [command, ...args] = process.argv.slice(2);
 
 const COMMANDS = {
   ideas:      () => listIdeas(args),
-  idea:       () => showIdea(args),
+  idea:       () => handleIdea(args),
   share:      () => shareIdea(),
   stake:      () => stakeOnIdea(args),
   fork:       () => forkIdea(args),
   specs:      () => listSpecs(args),
   spec:       () => showSpec(args),
-  contribute: () => contribute(),
+  contribute: () => contribute(args),
   status:     () => showStatus(),
   resonance:  () => showResonance(),
   identity:   () => handleIdentity(args),
   help:       () => showHelp(),
 };
 
+async function handleIdea(args) {
+  if (args[0] === "create") return createIdea(args.slice(1));
+  return showIdea(args);
+}
+
 async function handleIdentity(args) {
   const sub = args[0];
   const subArgs = args.slice(1);
@@ -38,6 +43,7 @@ async function handleIdentity(args) {
     case "unlink": return unlinkIdentity(subArgs);
     case "lookup": return lookupIdentity(subArgs);
     case "setup":  return setupIdentity();
+    case "set":    return setIdentity(subArgs);
     default:       return showIdentity();
   }
 }
@@ -51,20 +57,23 @@ function showHelp() {
 \x1b[1mExplore:\x1b[0m
   ideas [limit]           Browse ideas by ROI
   idea <id>               View idea detail
+  idea create <id> <name> [--desc "..." --value N --cost N --parent <id>]
   specs [limit]           List feature specs
   spec <id>               View spec detail
   resonance               What's alive right now
   status                  Network health + node info
 
 \x1b[1mContribute:\x1b[0m
-  share                   Submit a new idea
+  share                   Submit a new idea (interactive)
+  contribute              Record contribution (interactive)
+  contribute --type code --cc 5 --idea <id> --desc "what I did"
   stake <id> <cc>         Stake CC on an idea
   fork <id>               Fork an idea
-  contribute              Record any contribution
 
 \x1b[1mIdentity:\x1b[0m
   identity                Show your linked accounts
   identity setup          Guided onboarding
+  identity set <id>       Set identity non-interactively
   identity link <p> <id>  Link a provider (github, discord, ethereum, ...)
   identity unlink <p>     Unlink a provider
   identity lookup <p> <id> Find contributor by identity

package/lib/commands/contribute.mjs

@@ -1,14 +1,59 @@
 /**
  * Contribute command — record any contribution.
+ *
+ * Interactive:  cc contribute
+ * Non-interactive (for agents):
+ *   cc contribute --type code --cc 5 --idea <id> --desc "what I did"
  */
 
 import { post } from "../api.mjs";
 import { ensureIdentity } from "../identity.mjs";
-import { createInterface } from "node:readline/promises";
-import { stdin, stdout } from "node:process";
+import { getContributorId } from "../config.mjs";
 
-export async function contribute() {
+function parseFlags(args) {
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--type" && args[i + 1]) flags.type = args[++i];
+    else if (args[i] === "--cc" && args[i + 1]) flags.cc = parseFloat(args[++i]);
+    else if (args[i] === "--idea" && args[i + 1]) flags.idea = args[++i];
+    else if (args[i] === "--desc" && args[i + 1]) flags.desc = args[++i];
+  }
+  return flags;
+}
+
+export async function contribute(args = []) {
+  const flags = parseFlags(args);
+  const hasFlags = flags.type || flags.cc || flags.idea || flags.desc;
+
+  if (hasFlags) {
+    // Non-interactive mode (for agents and scripts)
+    const contributor = getContributorId() || process.env.COHERENCE_CONTRIBUTOR || "anonymous";
+    const type = flags.type || "other";
+    const amount = flags.cc || 1.0;
+    const ideaId = flags.idea || undefined;
+    const description = flags.desc || "";
+
+    const result = await post("/api/contributions/record", {
+      contributor_id: contributor,
+      type,
+      amount_cc: amount,
+      idea_id: ideaId,
+      metadata: { description },
+    });
+
+    if (result) {
+      console.log(`\x1b[32m✓\x1b[0m ${type} ${amount} CC${ideaId ? ` → ${ideaId}` : ""}${description ? ` (${description})` : ""}`);
+    } else {
+      console.log("Failed to record contribution.");
+      process.exit(1);
+    }
+    return;
+  }
+
+  // Interactive mode
   const contributor = await ensureIdentity();
+  const { createInterface } = await import("node:readline/promises");
+  const { stdin, stdout } = await import("node:process");
   const rl = createInterface({ input: stdin, output: stdout });
 
   console.log();

package/lib/commands/ideas.mjs

@@ -136,3 +136,44 @@ export async function forkIdea(args) {
     console.log("Fork failed.");
   }
 }
+
+/**
+ * Non-interactive idea creation for agents and scripts.
+ *
+ * Usage: cc idea create <id> <name> [--desc "..."] [--value N] [--cost N] [--parent <id>]
+ */
+export async function createIdea(args) {
+  if (args.length < 2) {
+    console.log("Usage: cc idea create <id> <name> [--desc \"...\"] [--value N] [--cost N] [--parent <id>]");
+    return;
+  }
+
+  const id = args[0];
+  const name = args[1];
+  const flags = {};
+  for (let i = 2; i < args.length; i++) {
+    if (args[i] === "--desc" && args[i + 1]) flags.desc = args[++i];
+    else if (args[i] === "--value" && args[i + 1]) flags.value = parseFloat(args[++i]);
+    else if (args[i] === "--cost" && args[i + 1]) flags.cost = parseFloat(args[++i]);
+    else if (args[i] === "--parent" && args[i + 1]) flags.parent = args[++i];
+    else if (args[i] === "--confidence" && args[i + 1]) flags.confidence = parseFloat(args[++i]);
+  }
+
+  const body = {
+    id,
+    name,
+    description: flags.desc || name,
+    potential_value: flags.value || 50,
+    estimated_cost: flags.cost || 5,
+    confidence: flags.confidence || 0.5,
+  };
+  if (flags.parent) body.parent_idea_id = flags.parent;
+
+  const result = await post("/api/ideas", body);
+  if (result) {
+    console.log(`\x1b[32m✓\x1b[0m Idea created: ${result.id || id}`);
+  } else {
+    console.log("Failed to create idea.");
+    process.exit(1);
+  }
+}

package/lib/commands/identity.mjs

@@ -86,6 +86,18 @@ export async function lookupIdentity(args) {
   }
 }
 
+export async function setIdentity(args) {
+  const id = args[0];
+  if (!id) {
+    console.log("Usage: cc identity set <contributor_id>");
+    console.log("Sets the contributor identity non-interactively (for agents and scripts).");
+    return;
+  }
+  const { saveConfig } = await import("../config.mjs");
+  saveConfig({ contributor_id: id });
+  console.log(`\x1b[32m✓\x1b[0m Identity set to: ${id}`);
+}
+
 export async function setupIdentity() {
   // Force re-run onboarding
   await ensureIdentity();

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "coherence-cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Coherence Network CLI — trace ideas from inception to payout, with fair attribution, coherence scoring, and 37 identity providers. No signup needed.",
   "type": "module",
   "bin": {
-    "cc": "bin/cc.mjs"
+    "cc": "bin/cc.mjs",
+    "coh": "bin/cc.mjs",
+    "coherence": "bin/cc.mjs"
   },
   "engines": {
     "node": ">=18.0.0"