@prongsjs/logs 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Drew Poling
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @prongsjs/logs
 
-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 Prongs logs profile: what happened, told to whoever runs the app. `log('audit.deleted', 'Page deleted', { pageId })` writes one structured JSON line with its level, and redacts values under secret-looking keys. Intents for audit, security, incident, job and debug, plus checks for `console` calls, catch blocks that only print, and secrets in logs.
+
+Add it with `npx prongs add logs`. Early (0.x): expect changes. Full guide: https://github.com/drewpoling2/prongs#readme

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+import type { Intent, Profile } from '@prongsjs/core';
+/**
+ * The logs profile: what happened, told to whoever runs the app. Each domain is a type of
+ * log (audit, security, incident, job, debug) and each intent a specific event within it,
+ * like `audit.deleted`. A ref-only `level.*` intent decides the level, whether it alerts, and
+ * whether it is kept in production, so changing `level.warn` changes every warning.
+ */
+export type LogLevel = 'error' | 'warn' | 'info' | 'debug';
+export type LogsBinding = {
+    level?: LogLevel;
+    /** Someone should be told now, not just find it later. */
+    alert?: boolean;
+    /** False: dropped in production builds. */
+    production?: boolean;
+};
+/** The types of log, in the order they are usually read. */
+export declare const LOG_DOMAINS: readonly ["audit", "security", "incident", "job", "debug"];
+export type LogDomain = (typeof LOG_DOMAINS)[number];
+export declare const logsProfile: Profile<LogsBinding>;
+/** The starter intents `prongs add logs` puts in a registry: types of log every app has. */
+export declare const LOG_INTENTS: Record<string, Intent<LogsBinding>>;

package/dist/index.js

@@ -0,0 +1,67 @@
+/** The types of log, in the order they are usually read. */
+export const LOG_DOMAINS = ['audit', 'security', 'incident', 'job', 'debug'];
+const domainOf = (id) => id.split('.')[0];
+export const logsProfile = {
+    name: 'logs',
+    domains: [...LOG_DOMAINS, 'level'],
+    internalDomains: ['level'],
+    validate(id, intent, defs) {
+        const issues = [];
+        if (domainOf(id) === 'level') {
+            if (intent.kind !== 'primitive')
+                issues.push('level intents are primitive: they hold the level, alerting and production settings');
+            if (!intent.binding?.level)
+                issues.push('binding.level must be one of error, warn, info, debug');
+            return issues;
+        }
+        const levels = (intent.refs ?? []).filter((ref) => domainOf(ref) === 'level');
+        if (intent.kind !== 'semantic' || levels.length !== 1)
+            issues.push('a log intent refs exactly one level.* intent, which sets its level');
+        if (intent.binding?.level)
+            issues.push('set the level through a level.* ref, not on the intent');
+        void defs;
+        return issues;
+    },
+    merge: (base, next) => ({ ...base, ...next }),
+};
+const level = (description, binding) => ({ kind: 'primitive', description, binding });
+const event = (ref, description, extra = {}) => ({
+    kind: 'semantic',
+    description,
+    refs: [`level.${ref}`],
+    ...extra,
+});
+/** The starter intents `prongs add logs` puts in a registry: types of log every app has. */
+export const LOG_INTENTS = {
+    'level.error': level('Error level: something is broken', { level: 'error' }),
+    'level.warn': level('Warning level: worth a look, not broken', { level: 'warn' }),
+    'level.info': level('Info level: a record of something that happened', { level: 'info' }),
+    'level.debug': level('Debug level: detail for development, dropped in production', { level: 'debug', production: false }),
+    'audit.created': event('info', 'Someone created something that matters later: an account, a page, an API key'),
+    'audit.changed': event('info', 'Someone changed something that matters: settings, a role, a published page'),
+    'audit.deleted': event('info', 'Someone deleted something: a page, an account, content'),
+    'audit.signedin': event('info', 'Someone signed in, the ordinary way', {
+        notFor: [{ context: 'a failed sign-in, or one from somewhere unusual', instead: 'security.signin' }],
+    }),
+    'audit.signedout': event('info', 'Someone signed out'),
+    'security.signin': event('warn', 'A sign-in failed, or succeeded from somewhere unusual', {
+        notFor: [{ context: 'an ordinary sign-in', instead: 'audit.signedin' }],
+    }),
+    'security.token': event('warn', 'A bad or expired token, secret or signature was presented'),
+    'security.limited': event('warn', 'A caller hit a rate limit'),
+    'incident.failed': event('error', 'Something broke and someone should look: a request, a job, a dependency', {
+        binding: { alert: true },
+        notFor: [
+            { context: 'something that recovered or fell back', instead: 'incident.degraded' },
+            { context: 'a caller’s own mistake, like invalid input: return a request.* error and do not log it as an incident' },
+        ],
+    }),
+    'incident.degraded': event('warn', 'It worked, but worse than it should: a fallback, a retry, a slow dependency'),
+    'job.started': event('info', 'A background job or script began: a sync, a backup, a migration'),
+    'job.finished': event('info', 'A job ended, with what it did: counts, duration', {
+        notFor: [{ context: 'a job that stopped on an error', instead: 'incident.failed' }],
+    }),
+    'debug.trace': event('debug', 'Detail for working on the code', {
+        notFor: [{ context: 'anything someone running the app needs to see', instead: 'job.finished' }],
+    }),
+};

package/dist/tooling/index.d.ts

@@ -0,0 +1,12 @@
+import type { ProfileTooling } from '@prongsjs/core/engine';
+export type LogsToolingOptions = {
+    cli?: string;
+    /** Where log() lives. Its own console calls are expected. */
+    helpersDir?: string;
+    /** Paths where console output is the point (scripts, tests, CLIs). */
+    consoleAllowed?: RegExp;
+};
+export declare const CONSOLE_ALLOWED: RegExp;
+export declare function createLogsTooling(options?: LogsToolingOptions): ProfileTooling;
+export { isConsoleCall, scanFile } from './scan.js';
+export { LOGS_RULE_DOCS, logsSpecTooling } from './spec.js';

package/dist/tooling/index.js

@@ -0,0 +1,68 @@
+import { locate } from '@prongsjs/core/engine';
+import { scanFile } from './scan.js';
+import { describeLogsBinding, logsSpecSection, logsUsage } from './spec.js';
+const SOURCE = /\.[cm]?[jt]sx?$/;
+export const CONSOLE_ALLOWED = /(^|\/)(scripts|bin|__tests__|tests?|e2e|cypress|playwright)\/|\.(test|spec|stories)\.[cm]?[jt]sx?$|(^|\/)[^/]*\.config\.[cm]?[jt]s$|(^|\/)global-(setup|teardown)\.[cm]?[jt]s$/;
+/** The log intent a console method most often means. */
+const CONSOLE_TO_LOG = {
+    error: 'incident.failed',
+    warn: 'incident.degraded',
+    info: 'job.finished',
+    log: 'debug.trace',
+    debug: 'debug.trace',
+    trace: 'debug.trace',
+};
+export function createLogsTooling(options = {}) {
+    const cli = options.cli ?? 'npx prongs';
+    const helpers = options.helpersDir?.replace(/\/+$/, '');
+    const consoleAllowed = options.consoleAllowed ?? CONSOLE_ALLOWED;
+    const scans = new WeakMap();
+    const scan = (ctx) => {
+        let result = scans.get(ctx.file);
+        if (!result)
+            scans.set(ctx.file, (result = scanFile(ctx.file.path, ctx.file.text)));
+        return result;
+    };
+    const isHelper = (path) => Boolean(helpers && (path === helpers || path.startsWith(`${helpers}/`)));
+    const at = (ctx, offset) => ({ path: ctx.file.path, ...locate(ctx.file.text, offset) });
+    const suggest = (ctx, id, example) => ctx.registry.has(id) ? { intent: id, text: `${example}: ${ctx.registry.defs[id].description}` } : { text: `${example} (add the starter intents with \`${cli} add logs\`)` };
+    /** A rule from a finder. Skips the helpers' own files, and files where console output is the point when `scriptsAllowed`. */
+    const rule = (id, severity, find, scriptsAllowed = false) => ({
+        id,
+        run(ctx) {
+            if (isHelper(ctx.file.path) || (scriptsAllowed && consoleAllowed.test(ctx.file.path)))
+                return [];
+            return find(ctx).map(({ offset, message, suggestions }) => ({ rule: id, severity, ...at(ctx, offset), message, suggestions }));
+        },
+    });
+    const rules = [
+        rule('raw-console', 'warning', (ctx) => scan(ctx).consoles.map(({ offset, method }) => ({
+            offset,
+            message: `console.${method}() is not a log intent: nothing says who needs to know, and it may run in production. Record it with log().`,
+            suggestions: [suggest(ctx, CONSOLE_TO_LOG[method] ?? 'debug.trace', `log('${CONSOLE_TO_LOG[method] ?? 'debug.trace'}', …)`)],
+        })), true),
+        rule('swallowed-error', 'error', (ctx) => scan(ctx).swallowed.map(({ offset }) => ({
+            offset,
+            message: 'This catch only prints the error, so nothing notices it failed. Record it with log() and handle it, or return an error with fail().',
+            suggestions: [suggest(ctx, 'incident.failed', "log('incident.failed', '…', { cause: error })")],
+        })), true),
+        rule('secret-in-log', 'error', (ctx) => scan(ctx).secrets.map(({ offset, name }) => ({
+            offset,
+            message: `"${name}" looks like a secret and is being logged. Logs are kept and shared; leave it out, or log only that it was present.`,
+            suggestions: [],
+        }))),
+    ];
+    return {
+        name: 'logs',
+        appliesTo: (path) => SOURCE.test(path) && !path.endsWith('.d.ts'),
+        findUsages(ctx) {
+            return scan(ctx).usages.map(({ offset, intent }) => ({ intent, via: 'log', ...at(ctx, offset) }));
+        },
+        rules,
+        describe: describeLogsBinding,
+        usage: logsUsage,
+        specSection: logsSpecSection,
+    };
+}
+export { isConsoleCall, scanFile } from './scan.js';
+export { LOGS_RULE_DOCS, logsSpecTooling } from './spec.js';

package/dist/tooling/scan.d.ts

@@ -0,0 +1,25 @@
+import ts from 'typescript';
+/** What the logs checks need from one file. Offsets point at the node to report. */
+export type LogsScan = {
+    /** log('audit.deleted', ...) calls, by intent. */
+    usages: {
+        offset: number;
+        intent: string;
+    }[];
+    /** console.* calls, unless they are the whole body of a catch (those are in `swallowed`). */
+    consoles: {
+        offset: number;
+        method: string;
+    }[];
+    /** Catch handlers that only print the error. */
+    swallowed: {
+        offset: number;
+    }[];
+    /** Log or console calls that pass something named like a secret. */
+    secrets: {
+        offset: number;
+        name: string;
+    }[];
+};
+export declare function isConsoleCall(node: ts.Node): node is ts.CallExpression;
+export declare function scanFile(path: string, text: string, logName?: string): LogsScan;

package/dist/tooling/scan.js

@@ -0,0 +1,84 @@
+import ts from 'typescript';
+const CONSOLE_METHODS = new Set(['log', 'info', 'warn', 'error', 'debug', 'trace']);
+const SECRET_NAME = /(token|secret|password|passwd|authorization|cookie|apikey|api_key|accesskey|privatekey|credential)/i;
+const MASKING = /(mask|redact|hash|obfuscate|truncate|censor)/i;
+const INTENT_ID = /^[a-z]+(\.[a-z]+){1,2}$/;
+export function isConsoleCall(node) {
+    return (ts.isCallExpression(node) &&
+        ts.isPropertyAccessExpression(node.expression) &&
+        ts.isIdentifier(node.expression.expression) &&
+        node.expression.expression.text === 'console' &&
+        CONSOLE_METHODS.has(node.expression.name.text));
+}
+function secretIn(args) {
+    let found;
+    const visit = (node) => {
+        if (found)
+            return;
+        // mask(token), redact(secret): already made safe to print.
+        if (ts.isCallExpression(node) && MASKING.test(node.expression.getText()))
+            return;
+        if (ts.isIdentifier(node) && SECRET_NAME.test(node.text))
+            found = node.text;
+        else if (ts.isPropertyAccessExpression(node) && SECRET_NAME.test(node.name.text) && node.name.text !== 'length')
+            found = node.getText();
+        else if (ts.isPropertyAssignment(node) && SECRET_NAME.test(node.name.getText()))
+            found = node.name.getText();
+        if (!found && !ts.isFunctionLike(node))
+            ts.forEachChild(node, visit);
+    };
+    args.forEach(visit);
+    return found;
+}
+/** A catch whose body only prints: `catch (e) { console.error(e) }` or `.catch((e) => console.log(e))`. */
+function onlyPrints(body) {
+    if (isConsoleCall(body))
+        return true;
+    if (ts.isBlock(body))
+        return body.statements.length > 0 && body.statements.every((s) => ts.isExpressionStatement(s) && isConsoleCall(s.expression));
+    return false;
+}
+export function scanFile(path, text, logName = 'log') {
+    const kind = path.endsWith('x') ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
+    const source = ts.createSourceFile(path, text, ts.ScriptTarget.Latest, true, kind);
+    const scan = { usages: [], consoles: [], swallowed: [], secrets: [] };
+    const inSwallowed = new Set();
+    const visit = (node) => {
+        if (ts.isCatchClause(node) && onlyPrints(node.block)) {
+            scan.swallowed.push({ offset: node.getStart(source) });
+            node.block.statements.forEach((s) => inSwallowed.add(s.expression));
+        }
+        if (ts.isCallExpression(node) &&
+            ts.isPropertyAccessExpression(node.expression) &&
+            node.expression.name.text === 'catch' &&
+            node.arguments[0] &&
+            ts.isArrowFunction(node.arguments[0]) &&
+            onlyPrints(node.arguments[0].body)) {
+            const handler = node.arguments[0];
+            scan.swallowed.push({ offset: handler.getStart(source) });
+            if (ts.isBlock(handler.body))
+                handler.body.statements.forEach((s) => inSwallowed.add(s.expression));
+            else
+                inSwallowed.add(handler.body);
+        }
+        if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === logName) {
+            const first = node.arguments[0];
+            if (first && (ts.isStringLiteral(first) || ts.isNoSubstitutionTemplateLiteral(first)) && INTENT_ID.test(first.text)) {
+                scan.usages.push({ offset: first.getStart(source), intent: first.text });
+                const secret = secretIn(node.arguments.slice(1));
+                if (secret)
+                    scan.secrets.push({ offset: node.getStart(source), name: secret });
+            }
+        }
+        if (isConsoleCall(node)) {
+            if (!inSwallowed.has(node))
+                scan.consoles.push({ offset: node.getStart(source), method: node.expression.name.text });
+            const secret = secretIn(node.arguments);
+            if (secret)
+                scan.secrets.push({ offset: node.getStart(source), name: secret });
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(source);
+    return scan;
+}

package/dist/tooling/spec.d.ts

@@ -0,0 +1,9 @@
+import type { AnyRegistry } from '@prongsjs/core';
+import type { RuleDoc, SpecContext, SpecTooling } from '@prongsjs/core/engine';
+/** `warn`, `error, alerts`, `debug, not in production`: next to each intent in the spec's index. */
+export declare function describeLogsBinding(binding: unknown): string;
+export declare function logsSpecSection(registry: AnyRegistry, context: SpecContext): string;
+/** What each logs rule finds, for the docs and for anyone reading a check report. */
+export declare const LOGS_RULE_DOCS: readonly RuleDoc[];
+export declare const logsUsage: (id: string) => string;
+export declare const logsSpecTooling: SpecTooling;

package/dist/tooling/spec.js

@@ -0,0 +1,57 @@
+import { LOG_DOMAINS } from '../index.js';
+/** `warn`, `error, alerts`, `debug, not in production`: next to each intent in the spec's index. */
+export function describeLogsBinding(binding) {
+    const b = binding;
+    if (!b.level)
+        return '';
+    return '`' + b.level + '`' + (b.alert ? ', alerts' : '') + (b.production === false ? ', not in production' : '');
+}
+export function logsSpecSection(registry, context) {
+    if (!registry.ids.some((id) => LOG_DOMAINS.includes(id.split('.')[0])))
+        return '';
+    const from = context.componentsImport ?? './components/prongs';
+    return [
+        '## Logs rules',
+        '',
+        `\`import { log } from '${from}/log';\``,
+        '',
+        "- Record events with `log('<type>.<event>', message, data)`, never `console.*`. Pick the type by who needs to know: who did what (`audit.*`), security signals (`security.*`), something broke or degraded (`incident.*`), background work (`job.*`), development only (`debug.*`). Then the event within it.",
+        '- A `catch` that only prints the error hides it. Record it with `incident.*` and handle it, or return an error with `fail()`.',
+        '- Never put tokens, secrets, passwords or cookies in a log; `log()` redacts keys that look like secrets, but leave them out.',
+        '',
+        '```ts',
+        "log('audit.deleted', 'Page deleted', { pageId, by: user.id });",
+        "log('incident.degraded', 'Search fell back to the cached index', { tookMs });",
+        "log('job.finished', 'Redirects synced', { count: entries.length });",
+        '```',
+    ].join('\n');
+}
+/** What each logs rule finds, for the docs and for anyone reading a check report. */
+export const LOGS_RULE_DOCS = [
+    {
+        id: 'raw-console',
+        profile: 'logs',
+        severity: 'warning',
+        summary: '`console.*` in app code. Nothing says who needs to know, and it may run in production. Scripts, tests, config files and the helpers themselves are left alone.',
+        bad: "console.error('[sync]', error);",
+        good: "log('incident.failed', 'Sync stopped', { cause: error });",
+    },
+    {
+        id: 'swallowed-error',
+        profile: 'logs',
+        severity: 'error',
+        summary: 'A `catch` whose only job is to print the error, so nothing notices the failure.',
+        bad: 'try { await sync(); } catch (e) { console.log(e); }',
+        good: "try { await sync(); } catch (e) { log('incident.failed', 'Sync stopped', { cause: e }); throw e; }",
+    },
+    {
+        id: 'secret-in-log',
+        profile: 'logs',
+        severity: 'error',
+        summary: 'Something named like a token, secret, password or cookie passed to a log, unless it goes through a masking function first.',
+        bad: "log('security.token', 'Bad token', { token });",
+        good: "log('security.token', 'Bad token', { tokenPresent: Boolean(token) });",
+    },
+];
+export const logsUsage = (id) => `log('${id}', 'What happened', { id });`;
+export const logsSpecTooling = { name: 'logs', describe: describeLogsBinding, specSection: logsSpecSection, usage: logsUsage };

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "@prongsjs/logs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "The Prongs logs profile: what happened, told to whoever runs the app. Audit, security, incident, job and debug intents, log(), and checks for console calls, swallowed errors and secrets in logs.",
+  "keywords": [
+    "intents",
+    "logging",
+    "structured-logs",
+    "ai-agents"
+  ],
+  "homepage": "https://github.com/drewpoling2/prongs#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/drewpoling2/prongs.git",
+    "directory": "packages/logs"
+  },
+  "bugs": {
+    "url": "https://github.com/drewpoling2/prongs/issues"
+  },
+  "author": "Drew Poling",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./tooling": {
+      "types": "./dist/tooling/index.d.ts",
+      "import": "./dist/tooling/index.js"
+    },
+    "./spec": {
+      "types": "./dist/tooling/spec.d.ts",
+      "import": "./dist/tooling/spec.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@prongsjs/core": "0.2.0"
+  },
+  "peerDependencies": {
+    "typescript": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}