ethos-cli 0.1.0

package/dist/skills-installer/lockfile.js

@@ -0,0 +1,23 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+export function lockPath() {
+    return join(homedir(), ".ethos", "skills.lock.json");
+}
+export async function readLockfile() {
+    try {
+        const parsed = JSON.parse(await readFile(lockPath(), "utf-8"));
+        if (parsed?.schemaVersion === 1)
+            return parsed;
+    }
+    catch {
+        // Missing or malformed lockfiles are treated as empty.
+    }
+    return { schemaVersion: 1, ethosVersion: "", skills: {} };
+}
+export async function writeLockfile(lock) {
+    const target = lockPath();
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, JSON.stringify(lock, null, 2) + "\n");
+}
+//# sourceMappingURL=lockfile.js.map

package/dist/skills-installer/lockfile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lockfile.js","sourceRoot":"","sources":["../../src/skills-installer/lockfile.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAgB1C,MAAM,UAAU,QAAQ;IACtB,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,kBAAkB,CAAC,CAAC;AACvD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,YAAY;IAChC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,QAAQ,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC;QAC/D,IAAI,MAAM,EAAE,aAAa,KAAK,CAAC;YAAE,OAAO,MAAkB,CAAC;IAC7D,CAAC;IAAC,MAAM,CAAC;QACP,uDAAuD;IACzD,CAAC;IACD,OAAO,EAAE,aAAa,EAAE,CAAC,EAAE,YAAY,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;AAC5D,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,IAAc;IAChD,MAAM,MAAM,GAAG,QAAQ,EAAE,CAAC;IAC1B,MAAM,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAClD,MAAM,SAAS,CAAC,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;AAChE,CAAC"}

package/dist/skills-installer/skill.d.ts

@@ -0,0 +1,9 @@
+export interface Skill {
+    name: string;
+    description: string;
+    sourcePath: string;
+    hash: string;
+}
+export declare function sanitizeName(name: string): string;
+export declare function isPathSafe(base: string, target: string): boolean;
+export declare function discoverBundledSkills(rootDir: string): Promise<Skill[]>;

package/dist/skills-installer/skill.js

@@ -0,0 +1,70 @@
+import { createHash } from "node:crypto";
+import { readFile, readdir } from "node:fs/promises";
+import { join, normalize, resolve, sep } from "node:path";
+export function sanitizeName(name) {
+    return (name
+        .toLowerCase()
+        .replace(/[^a-z0-9._]+/g, "-")
+        .replace(/^[.\-]+|[.\-]+$/g, "")
+        .substring(0, 255) || "unnamed-skill");
+}
+export function isPathSafe(base, target) {
+    const normalizedBase = normalize(resolve(base));
+    const normalizedTarget = normalize(resolve(target));
+    return (normalizedTarget === normalizedBase ||
+        normalizedTarget.startsWith(normalizedBase + sep));
+}
+function parseFrontmatter(content) {
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!match)
+        return null;
+    const result = {};
+    for (const line of match[1].split(/\r?\n/)) {
+        const kv = line.match(/^([a-zA-Z_][a-zA-Z0-9_-]*):\s*(.*)$/);
+        if (!kv)
+            continue;
+        let value = kv[2].trim();
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        result[kv[1]] = value;
+    }
+    return result;
+}
+async function readSkillFile(filePath, fallbackName) {
+    let content;
+    try {
+        content = await readFile(filePath, "utf-8");
+    }
+    catch {
+        return null;
+    }
+    const frontmatter = parseFrontmatter(content);
+    if (!frontmatter?.description)
+        return null;
+    return {
+        name: sanitizeName(frontmatter.name ?? fallbackName),
+        description: frontmatter.description,
+        sourcePath: filePath,
+        hash: createHash("sha256").update(content).digest("hex"),
+    };
+}
+export async function discoverBundledSkills(rootDir) {
+    const entries = await readdir(rootDir, { withFileTypes: true }).catch(() => []);
+    const skills = [];
+    for (const entry of entries) {
+        if (entry.isFile() && entry.name.endsWith(".md") && entry.name !== "README.md") {
+            const skill = await readSkillFile(join(rootDir, entry.name), entry.name.slice(0, -3));
+            if (skill)
+                skills.push(skill);
+        }
+        else if (entry.isDirectory()) {
+            const skill = await readSkillFile(join(rootDir, entry.name, "SKILL.md"), entry.name);
+            if (skill)
+                skills.push(skill);
+        }
+    }
+    return skills;
+}
+//# sourceMappingURL=skill.js.map

package/dist/skills-installer/skill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill.js","sourceRoot":"","sources":["../../src/skills-installer/skill.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "ethos-cli",
+  "version": "0.1.0",
+  "description": "Commander-based CLI for Ethos table operations",
+  "homepage": "https://github.com/cluster-software/ethos#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cluster-software/ethos.git",
+    "directory": "ethos-cli"
+  },
+  "bugs": {
+    "url": "https://github.com/cluster-software/ethos/issues"
+  },
+  "type": "module",
+  "bin": {
+    "ethos": "dist/bin/ethos.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "postinstall.cjs",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc",
+    "dev": "tsx src/bin/ethos.ts",
+    "postinstall": "node ./postinstall.cjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "changeset publish"
+  },
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.31.0",
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.6"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/postinstall.cjs

@@ -0,0 +1,23 @@
+// npm postinstall bootstrap.
+//
+// The published package contains dist/, but dev checkouts may run npm install
+// before a build. In that case this no-ops. Installer failures are logged and
+// swallowed so npm install itself never fails.
+"use strict";
+const fs = require("node:fs");
+const path = require("node:path");
+
+const target = path.join(__dirname, "dist", "scripts", "install-skills.js");
+
+if (!fs.existsSync(target)) {
+  process.exit(0);
+}
+
+import(target).catch((err) => {
+  process.stderr.write(
+    "ethos: skills install crashed (continuing) - " +
+      (err && err.message ? err.message : String(err)) +
+      "\n",
+  );
+  process.exit(0);
+});

package/skills/find-people-at-companies.md

@@ -0,0 +1,111 @@
+---
+name: find-people-at-companies
+description: Import a company CSV into Ethos, collect ICP and buying-signal criteria, create a people_sourcing agent, run it on the first rows, and open the table. Use when the user asks to find ICP-matching people at companies from a CSV or invokes /find-people-at-companies.
+---
+
+# find-people-at-companies
+
+Use this when the user wants Ethos to source people at a list of companies.
+The production CLI default is `https://api.ethos.hello-cluster.com`, so only
+pass `--api-url` for local development or an explicitly requested environment.
+
+## Inputs
+
+If the user has not already provided these, ask only for what is missing:
+
+- Company CSV path.
+- ICP fit criteria for companies.
+- Buying-signal criteria to prioritize.
+- Person titles/functions to return.
+- Desired max people per company. Default to 3 when unspecified.
+
+## Authenticate
+
+Check auth first:
+
+```sh
+ethos auth status --json
+```
+
+If unauthenticated, run:
+
+```sh
+ethos auth login
+```
+
+The browser claim flow handles production auth. Do not ask for API tokens unless
+the user explicitly wants a non-browser setup.
+
+## Import The CSV
+
+```sh
+ethos tables import-csv "$CSV_PATH" --entity-type company --json
+```
+
+Save `response.table_id`, `response.view_ids[0]`, and the relevant company
+input column ids from `response.columns`.
+
+## Create The Agent
+
+Create a `people_sourcing` agent. Use these abilities by default:
+
+```sh
+ethos agents create \
+  --name "People sourcing - <brief name>" \
+  --workflow-type people_sourcing \
+  --ability web-search \
+  --ability web-fetch \
+  --ability linkedin-company-lookup \
+  --ability linkedin-profile-lookup \
+  --instructions "$AGENT_INSTRUCTIONS" \
+  --json
+```
+
+Only add `--ability browser-use --tool-preset browser` when the requested
+signals require genuine interactivity, such as submitting forms, navigating a
+dynamic gated site, or retrieving information that normal search/fetch tools
+cannot access. Do not add browser use just for search results, static websites,
+LinkedIn lookup, press releases, jobs pages, or company pages.
+
+The instructions should include:
+
+- The user's ICP and buying-signal criteria.
+- The exact types of people to return.
+- Any exclusions the user stated.
+- Return 0 people with `not_icp_reason` when the company is not ICP.
+- Prefer founders, CEOs, GTM leaders, sales leaders, partnerships, revenue
+  operations, or founding GTM when relevant.
+- Avoid technical-only founders or CTOs unless the user explicitly asks for
+  technical buyers.
+- Avoid marketing-only people who do not appear to touch sales when the user is
+  looking for GTM or sales ownership.
+- Cite public source URLs for every person and fit claim.
+
+## Source People
+
+Run against the imported table view:
+
+```sh
+ethos tables source-people "$TABLE_ID" \
+  --view-id "$VIEW_ID" \
+  --agent-id "$AGENT_ID" \
+  --input-column "$COMPANY_INPUT_COLUMN_ID" \
+  --targeting-brief "$TARGETING_BRIEF" \
+  --max-contacts-per-company "$MAX_PEOPLE_PER_COMPANY" \
+  --created-by-codex \
+  --json
+```
+
+Use multiple `--input-column` flags when the table has separate useful company
+fields such as name, domain, LinkedIn URL, and description.
+
+## Open And Report
+
+Open the table in the production app:
+
+```sh
+open "https://ethos.hello-cluster.com/tables/$TABLE_ID"
+```
+
+Then report the table URL, run id, and the agent id. Keep the response concise
+and mention that the run is visible in Ethos.