@w32191/just-loop 0.1.1 → 0.1.3

package/README.md

@@ -30,14 +30,41 @@ Bun is only a maintenance and release prerequisite. It is not a runtime dependen
 
 ## Release
 
-Prerequisites: Node 20+, Bun, and a valid npm login/token.
-
-1. Run `npm login`.
-2. Run `npm whoami`.
-3. Confirm `@w32191` scope access with `npm access list packages @w32191` (or equivalent access check).
-4. Run `npm view @w32191/just-loop version`.
-   - For the first publish, a 404 is expected until the package exists.
-   - The real unblock condition is: `npm whoami` succeeds and scope access checks pass.
-5. Bump the package version.
-6. Run `npm run verify:publish`.
-7. Publish with `npm publish --access public`.
+Primary release flow uses GitHub Actions and only allows manual dispatch from `main`.
+
+### GitHub Actions release
+
+Prerequisites:
+
+- GitHub Actions release workflow is configured in this repository
+- npm Trusted Publisher is configured for this package
+
+Steps:
+
+1. Open the `Release` workflow in GitHub Actions from the `main` branch.
+2. Choose either:
+   - `auto-bump = patch|minor`, or
+   - `auto-bump = no` and provide `version = X.Y.Z`
+3. Optionally add one-line `notes`.
+4. Optionally set `dry_run = true` to validate without pushing, tagging, or publishing.
+
+The workflow will:
+
+1. Lock to the dispatched `main` commit SHA.
+2. Install dependencies with `bun install --frozen-lockfile`.
+3. Update `package.json` to the release version.
+4. Run `npm run verify:publish`.
+5. Generate a release notes artifact.
+6. On non-dry-run:
+   - commit the version bump to `main`
+   - create and push tag `vX.Y.Z`
+   - publish to npm with `npm publish --provenance --access public`
+   - create the GitHub Release
+
+### Local fallback
+
+If GitHub Actions is unavailable, the equivalent manual flow is:
+
+1. Bump the package version.
+2. Run `npm run verify:publish`.
+3. Publish with `npm publish --access public`.

package/dist/src/commands/parse-ralph-loop-command.js

@@ -15,6 +15,15 @@ export function parseRalphLoopCommand(input) {
         if (!rest.startsWith("--")) {
             break;
         }
+        if (/^--max-iterations=/.test(rest)) {
+            const valueMatch = rest.match(/^--max-iterations=([0-9]+)(?:\s+|$)/);
+            if (!valueMatch) {
+                throw new Error("invalid --max-iterations value");
+            }
+            maxIterations = Number(valueMatch[1]);
+            rest = rest.slice(valueMatch[0].length);
+            continue;
+        }
         if (/^--max(?:\s|$)/.test(rest)) {
             const valueMatch = rest.match(/^--max(?:\s+(\S+))(?:\s+|$)/);
             if (!valueMatch || !/^[0-9]+$/.test(valueMatch[1])) {
@@ -33,6 +42,15 @@ export function parseRalphLoopCommand(input) {
             rest = rest.slice(promiseMatch[0].length);
             continue;
         }
+        if (/^--completion-promise=/.test(rest)) {
+            const promiseMatch = rest.match(/^--completion-promise=([^\s]+)(?:\s+|$)/);
+            if (!promiseMatch) {
+                throw new Error("invalid --completion-promise format");
+            }
+            completionPromise = promiseMatch[1];
+            rest = rest.slice(promiseMatch[0].length);
+            continue;
+        }
         if (/^--strategy(?:\s|$)/.test(rest)) {
             const strategyMatch = rest.match(/^--strategy(?:\s+(\S+))(?:\s+|$)/);
             if (!strategyMatch) {
@@ -43,6 +61,20 @@ export function parseRalphLoopCommand(input) {
             }
             throw new Error("invalid --strategy value");
         }
+        if (/^--strategy=/.test(rest)) {
+            const strategyMatch = rest.match(/^--strategy=([^\s]+)(?:\s+|$)/);
+            if (!strategyMatch) {
+                throw new Error("invalid --strategy value");
+            }
+            if (strategyMatch[1] === "continue") {
+                rest = rest.slice(strategyMatch[0].length);
+                continue;
+            }
+            if (strategyMatch[1] === "reset") {
+                throw new Error("reset strategy is not supported in v1");
+            }
+            throw new Error("invalid --strategy value");
+        }
         throw new Error("unknown flag");
     }
     const prompt = rest.trim().replace(/\s+/g, " ");

package/dist/src/plugin/command-definitions.js

@@ -1,11 +1,12 @@
+import { DEFAULT_COMPLETION_PROMISE, DEFAULT_MAX_ITERATIONS_FALLBACK } from "../ralph-loop/constants.js";
 const RALPH_LOOP_TEMPLATE = `You are starting a Ralph Loop - a self-referential development loop that runs until task completion.
 
 ## How Ralph Loop Works
 
 1. You will work on the task continuously
-2. When you believe the task is FULLY complete, output: \`<promise>{{COMPLETION_PROMISE}}</promise>\`
+2. When you believe the task is FULLY complete, output the configured completion promise exactly as provided
 3. If you don't output the promise, the loop will automatically inject another prompt to continue
-4. Maximum iterations: Configurable (default 100)
+4. Maximum iterations: plugin config fallback (${DEFAULT_MAX_ITERATIONS_FALLBACK})
 
 ## Rules
 
@@ -17,16 +18,19 @@ const RALPH_LOOP_TEMPLATE = `You are starting a Ralph Loop - a self-referential
 
 ## Exit Conditions
 
-1. **Completion**: Output your completion promise tag when fully complete
+1. **Completion**: Output your completion promise when fully complete
 2. **Max Iterations**: Loop stops automatically at limit
 3. **Cancel**: User runs \`/cancel-ralph\` command
 
 ## Your Task
 
 Parse the arguments below and begin working on the task. The format is:
-\`"task description" [--completion-promise=TEXT] [--max-iterations=N] [--strategy=reset|continue]\`
+\`[--completion-promise=TEXT] [--max-iterations=N] [--strategy=continue] task description\`
 
-Default completion promise is "DONE" and default max iterations is 100.`;
+Aliases: \`--promise "TEXT"\`, \`--max N\`
+Reset strategy is not supported in v1.
+
+Default completion promise is the project default \`${DEFAULT_COMPLETION_PROMISE}\` and default max iterations follows the plugin config fallback (${DEFAULT_MAX_ITERATIONS_FALLBACK}).`;
 const CANCEL_RALPH_TEMPLATE = `Cancel the currently active Ralph Loop.
 
 This will:

package/dist/src/plugin/command-execute-before-handler.d.ts

@@ -0,0 +1,17 @@
+type LoopCore = {
+    startLoop: (sessionID: string, prompt: string, options: {
+        maxIterations?: number;
+        completionPromise?: string;
+    }) => Promise<unknown>;
+    cancelLoop: (sessionID: string) => Promise<unknown>;
+};
+type CommandExecuteBeforeInput = {
+    command?: unknown;
+    sessionID?: unknown;
+    arguments?: unknown;
+};
+type CommandExecuteBeforeOptions = {
+    defaultMaxIterations?: number;
+};
+export declare function handleCommandExecuteBefore(input: CommandExecuteBeforeInput, core: LoopCore, options?: CommandExecuteBeforeOptions): Promise<void>;
+export {};

package/dist/src/plugin/command-execute-before-handler.js

@@ -0,0 +1,24 @@
+import { parseRalphLoopCommand } from "../commands/parse-ralph-loop-command.js";
+function buildCommandLine(command, args) {
+    const normalized = command.startsWith("/") ? command : `/${command}`;
+    const trimmedArgs = args.trim();
+    return trimmedArgs.length > 0 ? `${normalized} ${trimmedArgs}` : normalized;
+}
+export async function handleCommandExecuteBefore(input, core, options = {}) {
+    if (typeof input.command !== "string")
+        return;
+    if (typeof input.sessionID !== "string")
+        return;
+    const args = typeof input.arguments === "string" ? input.arguments : "";
+    const command = parseRalphLoopCommand(buildCommandLine(input.command, args));
+    if (!command)
+        return;
+    if (command.kind === "cancel") {
+        await core.cancelLoop(input.sessionID);
+        return;
+    }
+    await core.startLoop(input.sessionID, command.prompt, {
+        maxIterations: command.maxIterations ?? options.defaultMaxIterations,
+        completionPromise: command.completionPromise,
+    });
+}

package/dist/src/plugin/config-handler.d.ts

@@ -1 +1 @@
-export declare function handleConfig(input: Record<string, unknown>): Promise<void>;
+export declare function handleConfig(input: Record<string, unknown>): Promise<import("../ralph-loop/types.js").RalphLoopRuntimeConfig>;

package/dist/src/plugin/config-handler.js

@@ -1,10 +1,15 @@
+import { resolvePluginConfig } from "./plugin-config.js";
 import { getBuiltinCommands } from "./command-definitions.js";
 export async function handleConfig(input) {
+    const resolvedConfig = resolvePluginConfig(input);
     const existingCommands = input.command && typeof input.command === "object"
         ? input.command
         : {};
-    input.command = {
-        ...getBuiltinCommands(),
-        ...existingCommands,
-    };
+    input.command = resolvedConfig.enabled
+        ? {
+            ...getBuiltinCommands(),
+            ...existingCommands,
+        }
+        : existingCommands;
+    return resolvedConfig;
 }

package/dist/src/plugin/create-plugin.d.ts

@@ -25,6 +25,14 @@ type ChatMessageOutput = {
 type EventInput = {
     event?: unknown;
 };
+type CommandExecuteBeforeInput = {
+    command?: unknown;
+    sessionID?: unknown;
+    arguments?: unknown;
+};
+type CommandExecuteBeforeOutput = {
+    parts?: unknown;
+};
 type ToolExecuteBeforeInput = {
     tool?: unknown;
     sessionID?: unknown;
@@ -39,6 +47,7 @@ export type PluginHooks = {
     "chat.message": (input: ChatMessageInput, output: ChatMessageOutput) => Promise<void>;
     event: (input: EventInput) => Promise<void>;
     config: (input: Record<string, unknown>) => Promise<void>;
+    "command.execute.before": (input: CommandExecuteBeforeInput, output: CommandExecuteBeforeOutput) => Promise<void>;
     "tool.execute.before": (input: ToolExecuteBeforeInput, output: ToolExecuteBeforeOutput) => Promise<void>;
 };
 export declare function createPlugin(ctx?: PluginInput, deps?: CreatePluginDeps): Promise<PluginHooks>;

package/dist/src/plugin/create-plugin.js

@@ -1,7 +1,9 @@
 import { createOpenCodeHostAdapter } from "../host-adapter/opencode-host-adapter.js";
 import { createLoopCore } from "../ralph-loop/loop-core.js";
+import { handleCommandExecuteBefore } from "./command-execute-before-handler.js";
 import { handleConfig } from "./config-handler.js";
 import { handleEvent } from "./event-handler.js";
+import { resolvePluginConfig } from "./plugin-config.js";
 import { handleToolExecuteBefore } from "./tool-execute-before-handler.js";
 function extractSessionID(input) {
     if (typeof input.sessionID === "string")
@@ -23,6 +25,7 @@ export async function createPlugin(ctx, deps = {}) {
         throw new Error("plugin context is required");
     const createAdapter = deps.createOpenCodeHostAdapter ?? createOpenCodeHostAdapter;
     const createCore = deps.createLoopCore ?? createLoopCore;
+    let resolvedConfig = resolvePluginConfig({});
     const adapter = createAdapter({
         directory: ctx.directory,
         client: {
@@ -36,10 +39,14 @@ export async function createPlugin(ctx, deps = {}) {
             },
         },
     });
-    const core = createCore({ rootDir: ctx.directory, adapter });
+    const core = createCore({
+        rootDir: ctx.directory,
+        adapter,
+        getConfig: () => resolvedConfig,
+    });
     return {
         config: async (input) => {
-            await handleConfig(input);
+            resolvedConfig = await handleConfig(input);
         },
         "chat.message": async (input, output) => {
             const sessionID = extractSessionID(input);
@@ -48,12 +55,25 @@ export async function createPlugin(ctx, deps = {}) {
             extractChatText(output.parts);
         },
         event: async (input) => {
+            if (!resolvedConfig.enabled)
+                return;
             if (!input.event)
                 return;
             await handleEvent(input.event, core);
         },
+        "command.execute.before": async (input) => {
+            if (!resolvedConfig.enabled)
+                return;
+            await handleCommandExecuteBefore(input, core, {
+                defaultMaxIterations: resolvedConfig.defaultMaxIterations,
+            });
+        },
         "tool.execute.before": async (input, output) => {
-            await handleToolExecuteBefore(input, output, core);
+            if (!resolvedConfig.enabled)
+                return;
+            await handleToolExecuteBefore(input, output, core, {
+                defaultMaxIterations: resolvedConfig.defaultMaxIterations,
+            });
         },
     };
 }

package/dist/src/plugin/plugin-config.d.ts

@@ -0,0 +1,6 @@
+import type { RalphLoopRuntimeConfig } from "../ralph-loop/types.js";
+type ConfigInput = Record<string, unknown> & {
+    ralph_loop?: unknown;
+};
+export declare function resolvePluginConfig(input: ConfigInput): RalphLoopRuntimeConfig;
+export {};

package/dist/src/plugin/plugin-config.js

@@ -0,0 +1,36 @@
+import { DEFAULT_MAX_ITERATIONS_FALLBACK, DEFAULT_STRATEGY } from "../ralph-loop/constants.js";
+function isObject(value) {
+    return typeof value === "object" && value !== null;
+}
+function parseEnabled(value) {
+    if (value === undefined)
+        return false;
+    if (typeof value === "boolean")
+        return value;
+    throw new Error("ralph_loop.enabled must be a boolean");
+}
+function parseDefaultMaxIterations(value) {
+    if (value === undefined)
+        return DEFAULT_MAX_ITERATIONS_FALLBACK;
+    if (typeof value === "number" && Number.isInteger(value) && value > 0)
+        return value;
+    throw new Error("ralph_loop.default_max_iterations must be a positive integer");
+}
+function parseDefaultStrategy(value) {
+    if (value === undefined)
+        return DEFAULT_STRATEGY;
+    if (value === "continue")
+        return value;
+    throw new Error("ralph_loop.default_strategy must be 'continue'");
+}
+export function resolvePluginConfig(input) {
+    if (input.ralph_loop !== undefined && !isObject(input.ralph_loop)) {
+        throw new Error("ralph_loop must be an object");
+    }
+    const rawConfig = isObject(input.ralph_loop) ? input.ralph_loop : {};
+    return {
+        enabled: parseEnabled(rawConfig.enabled),
+        defaultMaxIterations: parseDefaultMaxIterations(rawConfig.default_max_iterations),
+        defaultStrategy: parseDefaultStrategy(rawConfig.default_strategy),
+    };
+}

package/dist/src/plugin/tool-execute-before-handler.d.ts

@@ -5,6 +5,9 @@ type LoopCore = {
     }) => Promise<unknown>;
     cancelLoop: (sessionID: string) => Promise<unknown>;
 };
+type ToolExecuteBeforeOptions = {
+    defaultMaxIterations?: number;
+};
 type ToolExecuteBeforeInput = {
     tool?: unknown;
     sessionID?: unknown;
@@ -14,5 +17,5 @@ type ToolExecuteBeforeOutput = {
         name?: unknown;
     };
 };
-export declare function handleToolExecuteBefore(input: ToolExecuteBeforeInput, output: ToolExecuteBeforeOutput, core: LoopCore): Promise<void>;
+export declare function handleToolExecuteBefore(input: ToolExecuteBeforeInput, output: ToolExecuteBeforeOutput, core: LoopCore, options?: ToolExecuteBeforeOptions): Promise<void>;
 export {};

package/dist/src/plugin/tool-execute-before-handler.js

@@ -2,7 +2,7 @@ import { parseRalphLoopCommand } from "../commands/parse-ralph-loop-command.js";
 function normalizeCommandName(name) {
     return name.startsWith("/") ? name : `/${name}`;
 }
-export async function handleToolExecuteBefore(input, output, core) {
+export async function handleToolExecuteBefore(input, output, core, options = {}) {
     if (input.tool !== "skill")
         return;
     if (typeof input.sessionID !== "string")
@@ -17,7 +17,7 @@ export async function handleToolExecuteBefore(input, output, core) {
         return;
     }
     await core.startLoop(input.sessionID, command.prompt, {
-        maxIterations: command.maxIterations,
+        maxIterations: command.maxIterations ?? options.defaultMaxIterations,
         completionPromise: command.completionPromise,
     });
 }

package/dist/src/ralph-loop/constants.d.ts

@@ -1,2 +1,4 @@
 export declare const DEFAULT_STATE_PATH = ".loop/ralph-loop.local.md";
 export declare const DEFAULT_COMPLETION_PROMISE = "<promise>DONE</promise>";
+export declare const DEFAULT_MAX_ITERATIONS_FALLBACK = 100;
+export declare const DEFAULT_STRATEGY = "continue";

package/dist/src/ralph-loop/constants.js

@@ -1,2 +1,4 @@
 export const DEFAULT_STATE_PATH = ".loop/ralph-loop.local.md";
 export const DEFAULT_COMPLETION_PROMISE = "<promise>DONE</promise>";
+export const DEFAULT_MAX_ITERATIONS_FALLBACK = 100;
+export const DEFAULT_STRATEGY = "continue";

package/dist/src/ralph-loop/loop-core.d.ts

@@ -1,4 +1,5 @@
 import type { HostAdapter } from "../host-adapter/types.js";
+import type { RalphLoopRuntimeConfig } from "./types.js";
 export type LoopEvent = {
     type: "session.idle";
     sessionID: string;
@@ -12,6 +13,7 @@ export type LoopEvent = {
 export type CreateLoopCoreDeps = {
     rootDir: string;
     adapter: HostAdapter;
+    getConfig?: () => RalphLoopRuntimeConfig;
 };
 export type StartLoopOptions = {
     maxIterations?: number;

package/dist/src/ralph-loop/loop-core.js

@@ -1,13 +1,19 @@
-import { DEFAULT_COMPLETION_PROMISE } from "./constants.js";
+import { DEFAULT_COMPLETION_PROMISE, DEFAULT_MAX_ITERATIONS_FALLBACK, DEFAULT_STRATEGY } from "./constants.js";
 import { buildContinuationPrompt } from "./continuation-prompt.js";
 import { detectCompletion } from "./completion-detector.js";
 import { clearState, readState, writeState } from "./state-store.js";
 import { randomUUID } from "node:crypto";
 export function createLoopCore(deps) {
     const inFlight = new Map();
+    const getConfig = () => deps.getConfig?.() ?? {
+        enabled: true,
+        defaultMaxIterations: DEFAULT_MAX_ITERATIONS_FALLBACK,
+        defaultStrategy: DEFAULT_STRATEGY,
+    };
     const getToken = (state) => state.incarnation_token ?? state.started_at;
     return {
         async startLoop(sessionID, prompt, options = {}) {
+            const config = getConfig();
             const existing = await readState(deps.rootDir);
             if (existing?.active) {
                 const stillExists = await deps.adapter.sessionExists(existing.session_id);
@@ -26,7 +32,7 @@ export function createLoopCore(deps) {
                 session_id: sessionID,
                 prompt,
                 iteration: 0,
-                max_iterations: options.maxIterations,
+                max_iterations: options.maxIterations ?? config.defaultMaxIterations,
                 completion_promise: options.completionPromise ?? DEFAULT_COMPLETION_PROMISE,
                 message_count_at_start: messageCountAtStart,
                 incarnation_token: incarnationToken,
@@ -51,8 +57,23 @@ export function createLoopCore(deps) {
             }
             try {
                 const state = await readState(deps.rootDir);
-                if (!state || !state.active || state.session_id !== event.sessionID)
+                if (!state || !state.active)
+                    return;
+                if (state.session_id !== event.sessionID) {
+                    const observedSessionID = state.session_id;
+                    const observedToken = getToken(state);
+                    const stillExists = await deps.adapter.sessionExists(observedSessionID);
+                    if (!stillExists) {
+                        const currentState = await readState(deps.rootDir);
+                        if (currentState &&
+                            currentState.active &&
+                            currentState.session_id === observedSessionID &&
+                            getToken(currentState) === observedToken) {
+                            await clearState(deps.rootDir);
+                        }
+                    }
                     return;
+                }
                 const incarnationToken = getToken(state);
                 const inFlightToken = inFlight.get(event.sessionID);
                 if (inFlightToken === incarnationToken)

package/dist/src/ralph-loop/types.d.ts

@@ -10,3 +10,14 @@ export type RalphLoopState = {
     incarnation_token?: string;
     started_at: string;
 };
+export type RalphLoopDefaultStrategy = "continue";
+export type RalphLoopRuntimeConfig = {
+    enabled: boolean;
+    defaultMaxIterations: number;
+    defaultStrategy: RalphLoopDefaultStrategy;
+};
+export type RalphLoopPluginConfigInput = {
+    enabled?: unknown;
+    default_max_iterations?: unknown;
+    default_strategy?: unknown;
+};

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@w32191/just-loop",
   "type": "module",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "OpenCode plugin package for just-loop.",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SamWang32191/just-loop"
+  },
   "main": "./dist/src/index.js",
   "types": "./dist/src/index.d.ts",
   "exports": {