@aopslabs/aops 0.2.0

package/assets/skills/aops-install/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: aops-install
+description: Guide an AI agent through safe AOPS Community npm installation with an existing database, AOPS-managed Docker PostgreSQL, or detected local PostgreSQL; then verify migrations, Gateway assets, server health, and Cockpit. Use for install, initialize, configure, repair, verify, or setup explanation requests after installing @aopslabs/aops.
+---
+
+# AOPS Community installation
+
+Use the installed `aops` command as live truth. Run the relevant `--help` before any mutation; do not guess flags from this skill when the installed version differs.
+
+## Inspect first
+
+If the operator starts with `aops setup ai`, treat its copy-ready prompt as the
+handoff into this packaged skill. The prompt is only an entry point; this skill
+and the installed CLI's live help remain the detailed authority.
+
+Run mutation-free discovery:
+
+```sh
+aops --version
+aops setup init --yes --json
+```
+
+This setup envelope already includes installation, PostgreSQL, host, and Gateway
+readiness. Read its actions before choosing a path. Run `aops assets status` or
+`aops server status` separately only when that check is action-required and more
+detail is needed.
+
+Never place any PostgreSQL URL, application password, path 3 administrator
+password, AuthV2 password, admin key, or token in argv, logs, committed files,
+or chat. Use AOPS masked prompts or the documented private process environment.
+
+## Route by need
+
+| Need | Smallest surface |
+| --- | --- |
+| inspect choices and readiness | `aops setup init --yes --json` |
+| give any terminal AI agent a safe setup handoff | `aops setup ai` |
+| normal operator installation | `aops setup init` |
+| use an existing database URL | path `1`, then `aops setup server-env` |
+| let AOPS manage Docker PostgreSQL | path `2` |
+| create AOPS DB in PostgreSQL on this computer | path `3` |
+| connect only to an existing AOPS server | path `4` |
+| inspect or repair Gateway assets | `aops assets --help` |
+| operate an installed local server | `aops server --help` |
+
+Load only the section needed for the selected path. The current nested `--help`
+owns exact flags.
+
+## Normal interactive installation
+
+Prefer the normal setup menu:
+
+```sh
+aops setup init
+```
+
+All local-server paths use the normal `default` instance, API port `5900`, and
+independently supervised Cockpit port `5922`, verify
+migrations, install the verified Gateway for registered runtimes, reconcile the inert signed
+official catalog, and leave starter/demo user data untouched. Interactive
+setup applies after collecting the selected path's required private inputs; it
+does not ask redundant continue, asset-selection, or asset-confirmation
+questions. It automatically installs or repairs the verified AOPS core and
+gateway for every registered runtime. The core supplies a small neutral router,
+rich on-demand mounted-domain user guides, and public-safe collaboration and
+working-discipline references. Setup makes disciplines available but does not
+select one. Additional signed catalog packages are imported as discoverable,
+inert choices. Use `--agent-assets skip` or `--no-catalog`
+only when the operator explicitly opts out.
+
+Treat the connected database as migration truth. An empty AOPS schema starts
+from migration zero, valid per-domain migration prefixes resume from the next
+entry, and a current schema is verify-only. Do not use an older CLI, release,
+or setup-audit version to decide which migration runs.
+
+For automatic Docker PostgreSQL, the container port is loopback-only and dynamically assigned. A destructive reset removes only exact instance/root/secret label-verified resources:
+
+```sh
+aops server reset --remove-managed-postgres --confirm-data-loss --confirm-instance default
+aops setup init
+```
+
+Global AOPS skills and pointers are shared installation assets and remain installed after server reset.
+
+The default `trusted-local` server binds only to `127.0.0.1:5900`; it never
+trusts LAN or Tailscale interfaces. AOPS Server on `5900` and Cockpit on `5922`
+are independent services and neither redirects to the other. Community does
+not provide an authenticated non-loopback listener. Use a separate HTTPS
+`remote-session` target for South. When upgrading an old installation, repair
+the private env explicitly with `aops setup server-env --auth trusted-local`;
+the rewrite removes retired local-auth assignments without printing them.
+
+## Path safety notes
+
+Git clone is a secondary development path. The optional application image is
+built from the same exact public npm CLI/server closure and runs the normal
+`aops server setup` lifecycle inside the container. It is a distribution path,
+not a fifth interactive `setup init` path. Path `2` manages only its namespaced,
+label-verified PostgreSQL resources; unrelated Docker resources remain
+operator-owned.
+
+For path `1`, PostgreSQL is operator-owned and may be local, remote, managed,
+or separately containerized. Run interactive `aops setup init` and select path
+`1`; it asks for the PostgreSQL URL using masked input, then immediately tests
+the connection with TLS `require`. A saved URL is offered as a masked default
+on retry and can be kept or replaced. The TLS-policy menu appears only when the
+default encrypted connection fails. Use `verify-full` with a trusted CA and
+matching hostname; use `disable` only when the operator explicitly accepts
+unencrypted transport. For
+non-interactive work, inject `AOPS_PG_URL` privately or prepare it with
+`aops setup server-env`, then inspect `aops setup init --path 1
+--postgres-tls <policy> --yes --json`.
+
+For path `3`, prefer interactive setup. It probes loopback PostgreSQL, asks for
+an existing administrator role/password through masked input, creates a new
+dedicated login and database with a generated application password, stores only
+the application URL in the private user server-env, and runs the normal external
+migrations. The administrator password is never stored. If PostgreSQL is absent
+or stopped, return the platform-specific install/start actions reported by
+readiness; do not silently run an elevated package manager. Automation may use
+the private `AOPS_LOCAL_POSTGRES_ADMIN_PASSWORD` environment variable.
+`--local-postgres-admin-no-password` works only with PostgreSQL TCP trust auth;
+it does not bypass authentication or make Linux peer/socket auth work over
+loopback TCP. If the administrator password is unknown, stop and ask the
+operator to configure one through their local PostgreSQL administration flow
+(for example, interactive `sudo -u postgres psql` followed by `\password
+postgres`) before retrying.
+
+For path `4`, connect this CLI to an existing AOPS Server without installing or
+operating a local server or PostgreSQL. The interactive wizard asks for the
+endpoint and target name, checks the exact endpoint, persists and selects the
+target, and then offers browser-approved device login when required.
+
+External targets require HTTPS with `remote-session` and `system-ca`.
+`authv2-jwt-session` remains a one-release input alias and canonicalizes to
+`remote-session`. Plain HTTP is not a remote-session transport, including on
+Tailscale.
+
+Use the target commands when the operator wants explicit add/check/select
+steps:
+
+```sh
+aops target add --name remote --api-base-url https://aops.example.com \
+  --auth-provider remote-session --tls-policy system-ca --apply
+aops target doctor remote --json
+aops target use remote --apply
+```
+
+Run `aops auth login --target remote`; it uses the browser-approved device
+flow and forces a new remote session rather than accepting old local
+credentials. Verify with
+`aops auth status --target remote`; use normal
+`aops auth logout --target remote` to revoke the remote session.
+`--local-only` is an explicit fallback that clears only local credentials when
+remote revocation is unavailable.
+
+## Apply explicitly in automation
+
+Interactive `aops setup init` applies directly. For agents, CI, and scripts,
+run the selected path's mutation-free readiness first and apply only after its
+required actions and private inputs are understood:
+
+```sh
+aops setup init --path 2 --yes --json
+aops setup init --path 2 --plan-id sha256:<64-hex> --apply --yes --json
+
+aops setup init --path 3 --yes --json
+aops setup init --path 3 --plan-id sha256:<64-hex> --apply
+
+aops setup init --path 4 --api-base-url https://aops.example.com \
+  --target-name remote --target-auth-provider remote-session \
+  --target-tls-policy system-ca --yes --json
+aops setup init --path 4 --api-base-url https://aops.example.com \
+  --target-name remote --target-auth-provider remote-session \
+  --target-tls-policy system-ca --apply --yes --json
+```
+
+For paths 1-3, read `installerPlan.planId` from the mutation-free preview and
+pass that exact value to the apply command. A stale identity fails before any
+setup mutation. Never invent or reuse a plan id from another machine, source,
+path, or readiness snapshot.
+
+All paths install the verified Gateway for registered runtimes. Local-server
+paths also reconcile the inert signed official catalog. No path seeds
+starter/demo user data. Use `--agent-assets skip` or `--no-catalog` only for an
+explicit opt-out.
+
+If Gateway assets need a separate action, install for every runtime registered by this CLI:
+
+```sh
+aops assets install --target all --apply --json
+```
+
+Use `--target codex`, `--target claude`, comma-separated values such as `--target codex,claude`, or repeat `--target` for an explicit subset. Do not use `both`; it is not a selector.
+
+Do not supply a release directory in the normal npm flow. `--from-release` and `--agent-assets-release` are maintainer/offline recovery overrides only. Do not write runtime homes from npm `postinstall`; Gateway writes require the explicit guarded commands above.
+
+## Verify and hand off
+
+```sh
+aops server start --json
+aops server health --json
+aops cockpit start --json
+aops cockpit health --json
+aops assets status --verify full --json
+aops cockpit --no-open --json
+```
+
+For path `4`, replace the local lifecycle checks with:
+
+```sh
+aops target doctor <target-name> --json
+aops auth status --target <target-name> --json
+```
+
+For an operator who wants the server attached to a visible terminal with live
+logs, use the installed package's `launchers/aops-server.sh` on macOS/Linux or
+`launchers/aops-server.ps1` on Windows. It directly invokes the packaged Node
+launcher and Ctrl+C stops that foreground server. The matching
+`aops-cockpit.sh`/`.ps1` starts only the independent Cockpit process and prints
+its URL; it never starts the server implicitly. Do not copy database secrets
+into these scripts or their arguments.
+
+Read and report the apply result's migration verification, then report the
+selected path, server health, registered runtime binding states, and the
+separate server and Cockpit URLs. `aops server stop` must not stop Cockpit;
+`aops cockpit stop` must not stop the server. Never report success from process
+exit alone when JSON says
+action-required, conflict, or unhealthy.
+
+When setup remains incomplete, preserve the exact safe next action from the CLI output. Ask the operator only for missing authority or private configuration; do not bypass ownership conflicts, TLS decisions, or unknown user-owned runtime files.

package/assets/skills/aops-install/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "AOPS Installation"
+  short_description: "Guide agents through safe AOPS installation"
+  default_prompt: "Use $aops-install to inspect and complete this AOPS Community installation safely."

package/dist/commands/activity.js

@@ -0,0 +1,352 @@
+import { Command } from 'commander';
+import { logError, logSuccess } from '@aopslabs/xf-cli-ui';
+import { applyCommonOptions, compactPayload, normalizeNonEmpty } from '../utils/command.js';
+import { invokeHostedToolWithApiState, requireApiState, unwrapHostedToolResult, } from '../utils/agent-gateway.js';
+import { preferProjectNameBinding, resolveOwnerScopeIdFromBinding, resolveOwnerScopeIdFromProjectRecord, resolveProjectBindingContext, } from '../utils/project-context.js';
+import { buildHostedSugarEnvelope, buildOperatorCookbook, } from '../utils/hosted-sugar.js';
+import { GUIDE_PATHS } from '../utils/guide-paths.js';
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function unwrapResultData(result) {
+    if (isRecord(result) && Object.prototype.hasOwnProperty.call(result, 'data')) {
+        return result.data;
+    }
+    return result;
+}
+function toInteger(value, label) {
+    if (typeof value === 'number' && Number.isInteger(value))
+        return value;
+    const normalized = normalizeNonEmpty(value);
+    if (!normalized)
+        throw new Error(`${label} must be an integer.`);
+    const parsed = Number.parseInt(normalized, 10);
+    if (!Number.isInteger(parsed))
+        throw new Error(`${label} must be an integer.`);
+    return parsed;
+}
+function extractId(value) {
+    return normalizeNonEmpty(value);
+}
+function collectActivityArtifacts(result) {
+    const root = unwrapResultData(result) ?? (isRecord(result) ? result : {});
+    const activityItemId = extractId(root?.activityItemId) ?? extractId(root?.id);
+    return activityItemId ? { activityItemId } : undefined;
+}
+function jsonByteLength(value) {
+    try {
+        return Buffer.byteLength(JSON.stringify(value), 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+function summarizeText(value, maxLength = 240) {
+    const text = normalizeNonEmpty(value);
+    if (!text)
+        return undefined;
+    if (text.length <= maxLength)
+        return text;
+    return `${text.slice(0, maxLength - 3)}...`;
+}
+function summarizeUnknown(value) {
+    if (value === undefined)
+        return undefined;
+    if (isRecord(value)) {
+        const keys = Object.keys(value).sort();
+        return compactPayload({
+            kind: 'object',
+            keyCount: keys.length,
+            keys,
+            bytes: jsonByteLength(value),
+        });
+    }
+    if (Array.isArray(value)) {
+        return compactPayload({
+            kind: 'array',
+            length: value.length,
+            bytes: jsonByteLength(value),
+        });
+    }
+    return compactPayload({
+        kind: value === null ? 'null' : typeof value,
+        bytes: jsonByteLength(value),
+        preview: summarizeText(value, 80),
+    });
+}
+function summarizeRefs(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value))
+        return summarizeUnknown(value);
+    const types = Array.from(new Set(value
+        .map((entry) => (isRecord(entry) ? normalizeNonEmpty(entry.type) : undefined))
+        .filter((entry) => Boolean(entry)))).sort();
+    const preview = value.slice(0, 5).map((entry) => {
+        if (!isRecord(entry))
+            return entry;
+        return compactPayload({
+            type: normalizeNonEmpty(entry.type),
+            id: normalizeNonEmpty(entry.id),
+            label: summarizeText(entry.label, 80),
+        });
+    });
+    return compactPayload({
+        kind: 'array',
+        length: value.length,
+        types,
+        preview,
+        previewTruncated: value.length > preview.length ? true : undefined,
+        bytes: jsonByteLength(value),
+    });
+}
+function summarizeActivityRecord(value) {
+    if (!isRecord(value))
+        return value;
+    const summary = normalizeNonEmpty(value.summary);
+    const summaryPreview = summarizeText(summary);
+    return compactPayload({
+        id: normalizeNonEmpty(value.id),
+        scopeId: normalizeNonEmpty(value.scopeId),
+        projectId: normalizeNonEmpty(value.projectId),
+        sourceKind: normalizeNonEmpty(value.sourceKind),
+        sourceId: normalizeNonEmpty(value.sourceId),
+        action: normalizeNonEmpty(value.action),
+        status: normalizeNonEmpty(value.status),
+        summary: summaryPreview,
+        summaryBytes: summary ? Buffer.byteLength(summary, 'utf8') : undefined,
+        summaryTruncated: summary && summaryPreview !== summary ? true : undefined,
+        refsSummary: summarizeRefs(value.refs),
+        payloadSummary: summarizeUnknown(value.payload),
+        metaSummary: summarizeUnknown(value.meta),
+        createdAt: normalizeNonEmpty(value.createdAt),
+        updatedAt: normalizeNonEmpty(value.updatedAt),
+    });
+}
+function summarizeActivityListResult(result) {
+    if (Array.isArray(result))
+        return result.map(summarizeActivityRecord);
+    if (isRecord(result) && Array.isArray(result.data)) {
+        const data = result.data.map(summarizeActivityRecord);
+        return {
+            ...result,
+            data,
+            summary: {
+                ...(isRecord(result.summary) ? result.summary : {}),
+                mode: 'activity-list-summary',
+                count: data.length,
+                omitted: ['refs', 'payload', 'meta'],
+                fullRecordHint: 'Use `aops-cli activity get --id <activity-id> --json` without --summary for full refs/payload/meta.',
+            },
+        };
+    }
+    return summarizeActivityRecord(result);
+}
+function summarizeActivityGetResult(result) {
+    if (isRecord(result) && Object.prototype.hasOwnProperty.call(result, 'data')) {
+        return {
+            ...result,
+            data: summarizeActivityRecord(result.data),
+            summary: {
+                ...(isRecord(result.summary) ? result.summary : {}),
+                mode: 'activity-get-summary',
+                omitted: ['refs', 'payload', 'meta'],
+                fullRecordHint: 'Run without --summary for full refs/payload/meta.',
+            },
+        };
+    }
+    return summarizeActivityRecord(result);
+}
+function buildGatewayOptions(options, resolvedContext) {
+    return {
+        ...options,
+        ...preferProjectNameBinding(resolvedContext),
+    };
+}
+async function hydrateProjectContext(apiState, options, resolvedContext) {
+    const projectId = normalizeNonEmpty(resolvedContext.projectId);
+    if (!projectId)
+        return resolvedContext;
+    if (normalizeNonEmpty(options.scopeId))
+        return resolvedContext;
+    const payload = await invokeHostedToolWithApiState(apiState, {
+        ...buildGatewayOptions(options, resolvedContext),
+        toolId: 'agentspace.project.get-by-id',
+        input: { id: projectId },
+    });
+    const result = unwrapHostedToolResult(payload);
+    const project = unwrapResultData(result);
+    if (!isRecord(project))
+        return resolvedContext;
+    const scopeId = resolveOwnerScopeIdFromProjectRecord(project, resolvedContext.scopeId);
+    const projectName = normalizeNonEmpty(project.name) ?? resolvedContext.projectName;
+    return {
+        ...resolvedContext,
+        scopeId,
+        projectName,
+    };
+}
+async function resolveActivityContext(options, apiState) {
+    const resolved = await resolveProjectBindingContext(options, {
+        requireProject: false,
+    });
+    const scopeId = normalizeNonEmpty(options.scopeId) ?? resolveOwnerScopeIdFromBinding(resolved);
+    return hydrateProjectContext(apiState, options, {
+        ...resolved,
+        scopeId,
+    });
+}
+function buildResolvedContextRecord(context) {
+    return compactPayload({
+        repoRoot: context.repoRoot,
+        configPath: context.configPath,
+        configFound: context.configFound,
+        scopeId: context.scopeId,
+        projectId: context.projectId,
+        projectName: context.projectName,
+    });
+}
+const buildEnvelope = buildHostedSugarEnvelope;
+function ensureActivityId(id, label = '--id') {
+    const resolved = normalizeNonEmpty(id);
+    if (!resolved)
+        throw new Error(`Provide ${label}.`);
+    return resolved;
+}
+export async function runActivityList(options = {}) {
+    try {
+        const apiState = await requireApiState(options);
+        if (!apiState)
+            return;
+        const resolvedContext = await resolveActivityContext(options, apiState);
+        const input = {
+            filter: compactPayload({
+                scopeId: normalizeNonEmpty(resolvedContext.scopeId),
+                scopeResolution: options.scopeResolution,
+                projectId: normalizeNonEmpty(options.filterProjectId),
+                sourceKind: normalizeNonEmpty(options.sourceKind),
+                sourceId: normalizeNonEmpty(options.sourceId),
+                action: normalizeNonEmpty(options.action),
+                status: normalizeNonEmpty(options.status),
+            }),
+            options: compactPayload({
+                limit: options.limit !== undefined ? toInteger(options.limit, '--limit') : undefined,
+            }),
+        };
+        const payload = await invokeHostedToolWithApiState(apiState, {
+            ...buildGatewayOptions(options, resolvedContext),
+            tenantId: options.tenantId,
+            locale: options.locale,
+            fallbackLocale: options.fallbackLocale,
+            timeoutMs: options.timeoutMs,
+            apiBaseUrl: options.apiBaseUrl,
+            accessToken: options.accessToken,
+            refreshToken: options.refreshToken,
+            toolId: 'agentspace.activity-item.list-activity-items',
+            input,
+        });
+        const result = unwrapHostedToolResult(payload);
+        const outputResult = options.summary ? summarizeActivityListResult(result) : result;
+        if (options.json) {
+            console.log(JSON.stringify(buildEnvelope({
+                command: 'activity.list',
+                toolId: 'agentspace.activity-item.list-activity-items',
+                resolvedContext: buildResolvedContextRecord(resolvedContext),
+                input,
+                result: outputResult,
+            }), null, 2));
+            return;
+        }
+        logSuccess('Activity list loaded.');
+        console.log(JSON.stringify(outputResult, null, 2));
+    }
+    catch (error) {
+        logError(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+}
+export async function runActivityGet(options = {}) {
+    try {
+        const apiState = await requireApiState(options);
+        if (!apiState)
+            return;
+        const resolvedContext = await resolveActivityContext(options, apiState);
+        const id = ensureActivityId(options.id);
+        const input = { id };
+        const payload = await invokeHostedToolWithApiState(apiState, {
+            ...buildGatewayOptions(options, resolvedContext),
+            tenantId: options.tenantId,
+            locale: options.locale,
+            fallbackLocale: options.fallbackLocale,
+            timeoutMs: options.timeoutMs,
+            apiBaseUrl: options.apiBaseUrl,
+            accessToken: options.accessToken,
+            refreshToken: options.refreshToken,
+            toolId: 'agentspace.activity-item.get-by-id',
+            input,
+        });
+        const result = unwrapHostedToolResult(payload);
+        const outputResult = options.summary ? summarizeActivityGetResult(result) : result;
+        if (options.json) {
+            console.log(JSON.stringify(buildEnvelope({
+                command: 'activity.get',
+                toolId: 'agentspace.activity-item.get-by-id',
+                resolvedContext: buildResolvedContextRecord(resolvedContext),
+                input,
+                artifacts: collectActivityArtifacts(result),
+                result: outputResult,
+            }), null, 2));
+            return;
+        }
+        logSuccess('Activity item loaded.');
+        console.log(JSON.stringify(outputResult, null, 2));
+    }
+    catch (error) {
+        logError(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+}
+function applyActivityContextOptions(cmd, params = {}) {
+    applyCommonOptions(cmd);
+    cmd.option('--project-id <id>', 'Project id used to resolve repo-bound activity ownership');
+    cmd.option('--project-name <name>', 'Project name used to resolve repo-bound activity ownership');
+    cmd.option('--scope-id <id>', 'Explicit scope id override for activity ownership');
+    if (params.withScopeResolution) {
+        cmd.option('--scope-resolution <mode>', 'Scope resolution policy: explicit or cascade');
+    }
+    return cmd;
+}
+export function makeActivityCommand() {
+    const cmd = new Command('activity').description('Agentspace activity ledger read sugar over the hosted AOPS gateway');
+    applyActivityContextOptions(cmd.command('list')
+        .description('List activity ledger items')
+        .option('--source-kind <kind>', 'Source kind filter: aops-cli, desktop, runner, system')
+        .option('--source-id <id>', 'Source id filter')
+        .option('--action <text>', 'Action filter')
+        .option('--status <status>', 'Status filter: success or error')
+        .option('--filter-project-id <id>', 'Activity projectId filter; separate from context --project-id')
+        .option('--limit <n>', 'Optional item limit')
+        .option('--summary', 'Print compact activity records and omit raw refs/payload/meta'), { withScopeResolution: true }).action(async (options) => {
+        await runActivityList(options);
+    });
+    applyActivityContextOptions(cmd.command('get')
+        .description('Get an activity ledger item by id')
+        .requiredOption('--id <id>', 'Activity item id')
+        .option('--summary', 'Omit raw refs/payload/meta and print compact size summaries')).action(async (options) => {
+        await runActivityGet(options);
+    });
+    cmd.addHelpText('after', buildOperatorCookbook({
+        examples: [
+            'aops-cli activity list --summary --limit 20 --json',
+            'aops-cli activity list --source-kind aops-cli --status success --summary --json',
+            'aops-cli activity get --id <activity-id> --summary --json',
+        ],
+        guide: GUIDE_PATHS.agentspace,
+        notes: [
+            'Activity commands are read-only and do not require --apply.',
+            'Use --summary for inventories because activity refs, payload, and meta can be large.',
+            'Use `aops-cli agent tools --domain agentspace --q activity --summary --json` for raw hosted operations not covered by this sugar.',
+        ],
+    }));
+    return cmd;
+}