@webship.co/workspace-graph 0.0.0-stage → 1.0.0-alpha1

package/README.md

@@ -1,3 +1,25 @@
-# Temporary Holding Version
+# @webship.co/workspace-graph
 
-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.
+The **Graphs** workspace of the [Webship Workspace](https://github.com/webship/workspace) dashboard:
+the `graphs/` folder (type `code`), its settings file (`core/config/workspace.graphs.settings.yml`),
+its commands and its docs, as a plugin.
+
+## Use it
+
+```bash
+cd ~/workspace
+bash core/scripts/plugins.sh --require github:webship/workspace-graph
+bash core/scripts/plugins.sh --activate graph     # puts `graphs` on the workspaces list of settings.yml
+bash core/scripts/plugins.sh --install graph      # the folder, its settings file (once), its commands, its docs (once)
+```
+
+The settings file and the docs are placed once and never overwritten: they hold what you put there.
+`--deactivate` takes the workspace off the list; the folder and its content stay.
+
+## The commands
+
+| Command |
+| --- |
+| `cmd-tools-graphs.sh` |
+
+The bash functions these commands call live in the dashboard's `core/scripts/functions`.

package/commands/cmd-tools-graphs.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+
+# workspace-name: Graphs (list, collect, serve over MCP)
+
+# Bootstrap.
+# Find the workspace tooling from this script, so a fresh clone needs no setup.
+WORKSPACE_SCRIPTS="${WORKSPACE_SCRIPTS:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../core/scripts" && pwd)}";
+source ${WORKSPACE_SCRIPTS}/bootstrap.sh || exit 1 ;
+
+# Load workspace settings.
+eval $(parse_yaml ${WORKSPACE_CONFIG}/workspace.graphs.settings.yml);
+
+ARGPARSE_DESCRIPTION="Work with the project knowledge graphs kept in ~/workspace/graphs/"
+source ${WORKSPACE_SCRIPTS}/args/arg-graphs.sh || exit 1 ;
+
+shift $#;
+
+graphs_command ;

package/config/workspace.graphs.settings.yml

@@ -0,0 +1,25 @@
+doc:
+  name: graphs
+
+# Knowledge graphs built by cmd-tools-graphify.sh, one directory per project:
+#   graphs/<workspace>/<project>/{graph.json,GRAPH_REPORT.md,graph.html}
+# They live HERE rather than inside the project on purpose: graphify writes tens of MB, Leiden
+# clustering is not bit-stable so every rebuild diffs in full, and half the projects worth mapping
+# are git repositories we ship — a recipe like products/website_starter must not gain a graphify-out/ or a
+# CLAUDE.md block just because someone mapped it.
+presentation:
+  icon: tabler:hierarchy-2
+  subtitle: Project Knowledge Graphs
+  noun: graph
+  kind: files
+
+# What this folder's projects are, and which actions their rows offer:
+# sites | code | files | media | ai-items — see core/workspace-app/WORKSPACES.md.
+type: code
+
+# What the assistant is called on THIS workspace's page, and what its composer says when empty.
+# `default` in either means "whatever settings.yml says" — the global value, so a rename there
+# still reaches this page. Set a value here to override it for this workspace alone.
+assistant:
+  name: default
+  placeholder: default

package/dist/src/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The Graphs workspace for Webship Workspace: the `graphs/` folder as a plugin.
+ *
+ * What the package carries is placed by the installer from the manifest (the folder's settings file,
+ * its commands and its docs) and listed by --activate; the dashboard draws the workspace from the
+ * settings file like any other. Nothing to register at run time yet: this is where the folder's own
+ * rail buttons, row menus or assistant context would go.
+ */
+import type { PluginApi } from '@webship.co/workspace-plugin-api';
+export declare const WORKSPACE_KEY = "graphs";
+export declare function register(api: PluginApi): void;

package/dist/src/index.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * The Graphs workspace for Webship Workspace: the `graphs/` folder as a plugin.
+ *
+ * What the package carries is placed by the installer from the manifest (the folder's settings file,
+ * its commands and its docs) and listed by --activate; the dashboard draws the workspace from the
+ * settings file like any other. Nothing to register at run time yet: this is where the folder's own
+ * rail buttons, row menus or assistant context would go.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WORKSPACE_KEY = void 0;
+exports.register = register;
+exports.WORKSPACE_KEY = 'graphs';
+function register(api) {
+    api.addAssistantContext(() => `The graphs/ workspace is the Graphs workspace (a plugin, @webship.co/workspace-graph); its commands are the cmd-*.sh scripts in that folder.`);
+}
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAMH,4BAEC;AAJY,QAAA,aAAa,GAAG,QAAQ,CAAC;AAEtC,SAAgB,QAAQ,CAAC,GAAc;IACrC,GAAG,CAAC,mBAAmB,CAAC,GAAG,EAAE,CAAC,8IAA8I,CAAC,CAAC;AAChL,CAAC"}

package/docs/AGENTS.md

@@ -0,0 +1,29 @@
+# Graphs
+
+Every project's knowledge graph, one directory per project:
+`graphs/<workspace>/<project>/` with `graph.json`, `GRAPH_REPORT.md` and `graph.html`.
+
+Part of the **Webship Workspace** (`~/workspace`), a DDEV-only harness. The rules in the root
+`CLAUDE.md` apply here too; what follows is what is specific to this folder.
+
+## Why the graph is not in the project
+
+A graph is tens of megabytes, its clustering is not bit-stable so every rebuild re-diffs in full,
+and many of the projects worth mapping are repositories we ship — none should gain a generated
+directory because somebody mapped it. `cmd-tools-graphify.sh` builds it in the project's own
+workspace folder and the result is moved here.
+
+**Build one from the project's workspace, never from here:**
+
+```bash
+cd ~/workspace/dev && bash cmd-tools-graphify.sh <project>
+```
+
+## Commands here
+
+```bash
+bash cmd-tools-graphs.sh                              # Graphs (list, collect, serve over MCP)
+```
+
+Every one locates the workspace from its own path, so there is nothing to export and nothing to
+install. `--help` on any of them lists its arguments.

package/docs/CLAUDE.md

@@ -0,0 +1,7 @@
+# Graphs — workspace context
+
+You are inside the **graphs** workspace of the Webship Workspace (`~/workspace`).
+
+@AGENTS.md
+
+The rules in it apply to everything under this folder, however deep.

package/docs/README.md

@@ -0,0 +1,11 @@
+# Graphs
+
+Knowledge graphs of a project's code, one directory per project:
+`graphs/<workspace>/<project>/`.
+
+They live here rather than inside the project on purpose. A graph is tens of megabytes, its
+clustering is not bit-stable so every rebuild diffs in full, and half the projects worth mapping
+are repositories we ship — none of them should gain a graph directory because somebody mapped it.
+
+A graph answers *what depends on what*, deterministically, from the code. For *where is this
+explained or configured*, see `rag/` — the two are complements, not alternatives.

package/features/graph.feature

@@ -0,0 +1,12 @@
+Feature: The Graphs workspace plugin
+  Once the plugin is activated and installed, the graphs workspace is on the dashboard, and the
+  Plugins page lists the plugin with its four steps.
+
+  Scenario: The workspace page is there
+    Given I am on "/graphs"
+     Then I should see "Graphs"
+
+  Scenario: The plugin is listed on the Plugins page
+    Given I am on "/settings/plugins"
+     Then I should see "Graphs"
+      And I should see "@webship.co/workspace-graph"

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@webship.co/workspace-graph",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0-alpha1",
+  "description": "The Graphs workspace for Webship Workspace: the `graphs/` folder (type code), its settings file, its 1 commands and its docs, activated as a plugin.",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/webship/workspace-graph.git"
+  },
+  "files": [
+    "dist/src",
+    "commands",
+    "config",
+    "docs",
+    "features",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepare": "npm run build",
+    "test": "npm run build && node --test dist/tests/*.test.js",
+    "lint": "tsc -p tsconfig.json --noEmit"
+  },
+  "workspacePlugin": {
+    "name": "graph",
+    "label": "Graphs",
+    "workspace": {
+      "key": "graphs",
+      "settingsTemplate": "config/workspace.graphs.settings.yml",
+      "files": [
+        "commands/cmd-tools-graphs.sh"
+      ],
+      "docs": [
+        "docs/AGENTS.md",
+        "docs/CLAUDE.md",
+        "docs/README.md"
+      ]
+    },
+    "features": [
+      "features/graph.feature"
+    ]
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@webship.co/workspace-plugin-api": "^1.0.0-alpha1",
+    "typescript": "^5.9.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}