enable moddable for decentralized from path

Author: goldsteinsveta

.changeset/decentralize-path-moddable.md

@@ -0,0 +1,5 @@
+---
+"playground-cli": minor
+---
+
+`playground decentralize --path` can now publish moddable apps: the interactive flow asks "let others remix (mod) this app?" when publishing a local directory to the playground (with the same git-origin preflight and recovery menu as `playground deploy`), and headless mode accepts a `--moddable` flag. Publishing a local directory also inlines its README.md as the app's playground detail page, and the TUI now says so up front at the publish prompt. Mirrored URL sites are unchanged (no git source — never moddable, no README).

src/commands/decentralize/DecentralizeScreen.tsx

@@ -48,6 +48,7 @@ import {
     type DecentralizeOutcome,
     type DecentralizeSource,
 } from "../../utils/decentralize/run.js";
+import { ModdableErrorStage, ModdablePreflightStage } from "../deploy/ModdableStages.js";
 import {
     pickNextStage,
     validateDomainInput,
@@ -82,6 +83,13 @@ export interface DecentralizeScreenProps {
      * publish prompt is shown.
      */
     initialPublishToPlayground: boolean | null;
+    /**
+     * Pre-set when `--moddable` was passed on the CLI: skips the moddable
+     * prompt and drives straight into the git-origin preflight (only if the
+     * user ends up in the path + publish flow — URL mode ignores it). `null`
+     * means the prompt is shown.
+     */
+    initialModdable: boolean | null;
     onDone: (result: DecentralizeResult) => void;
 }
 
@@ -92,6 +100,7 @@ export function DecentralizeScreen({
     explicitSigner,
     sessionSigner,
     initialPublishToPlayground,
+    initialModdable,
     onDone,
 }: DecentralizeScreenProps) {
     // A caller-provided site URL pre-selects the URL flow (vestigial today —
@@ -114,6 +123,8 @@ export function DecentralizeScreen({
     const [publishToPlayground, setPublishToPlayground] = useState<boolean | null>(
         initialPublishToPlayground,
     );
+    const [moddable, setModdable] = useState<boolean | null>(initialModdable);
+    const [repositoryUrl, setRepositoryUrl] = useState<string | null>(null);
 
     const [stage, setStage] = useState<Stage>(() =>
         pickNextStage({
@@ -124,6 +135,8 @@ export function DecentralizeScreen({
             domainLabel: null,
             domainRaw: initialDot,
             publishToPlayground: initialPublishToPlayground,
+            moddable: initialModdable,
+            repositoryUrl: null,
         }),
     );
 
@@ -136,6 +149,8 @@ export function DecentralizeScreen({
             domainLabel: string | null;
             domainRaw: string | null;
             publishToPlayground: boolean | null;
+            moddable: boolean | null;
+            repositoryUrl: string | null;
         }> = {},
     ) => {
         setStage(
@@ -150,10 +165,21 @@ export function DecentralizeScreen({
                     next.publishToPlayground !== undefined
                         ? next.publishToPlayground
                         : publishToPlayground,
+                moddable: next.moddable !== undefined ? next.moddable : moddable,
+                repositoryUrl:
+                    next.repositoryUrl !== undefined ? next.repositoryUrl : repositoryUrl,
             }),
         );
     };
 
+    // Single "user declined moddable" transition, shared by the remix prompt's
+    // "no" answer and the setup-error menu's "continue without moddable", so
+    // the two paths can't drift apart. Mirrors deploy's helper of the same name.
+    const declineModdable = () => {
+        setModdable(false);
+        advance({ moddable: false });
+    };
+
     // Compose the active signer for downstream stages. Memoised so the
     // ResolvedSigner identity stays stable across re-renders (the dev branch
     // would otherwise produce a fresh `createDevPublishSigner()` instance on
@@ -316,24 +342,82 @@ export function DecentralizeScreen({
             )}
 
             {stage.kind === "prompt-publish" && (
+                <>
+                    {sourceKind === "path" && (
+                        <Callout tone="accent" title="Your app detail page">
+                            <Text>
+                                If you publish, the README.md in your directory becomes your app's
+                                detail page on the playground. Make sure it's up to date.
+                            </Text>
+                        </Callout>
+                    )}
+                    <Select<boolean>
+                        label="publish to the playground registry?"
+                        options={[
+                            {
+                                value: false,
+                                label: "no",
+                                hint: "just register the .dot name (DotNS only)",
+                            },
+                            {
+                                value: true,
+                                label: "yes",
+                                hint: "list the site in the playground apps tab",
+                            },
+                        ]}
+                        onSelect={(choice) => {
+                            setPublishToPlayground(choice);
+                            advance({ publishToPlayground: choice });
+                        }}
+                    />
+                </>
+            )}
+
+            {stage.kind === "prompt-moddable" && (
                 <Select<boolean>
-                    label="publish to the playground registry?"
+                    label="let others remix (mod) this app?"
                     options={[
-                        {
-                            value: false,
-                            label: "no",
-                            hint: "just register the .dot name (DotNS only)",
-                        },
                         {
                             value: true,
                             label: "yes",
-                            hint: "list the mirrored site in the playground apps tab",
+                            hint: "record my public GitHub repo so others can `playground mod` it",
+                        },
+                        {
+                            value: false,
+                            label: "no",
+                            hint: "keep my source private",
                         },
                     ]}
-                    onSelect={(choice) => {
-                        setPublishToPlayground(choice);
-                        advance({ publishToPlayground: choice });
+                    initialIndex={0}
+                    onSelect={(yes) => {
+                        if (yes) {
+                            setModdable(true);
+                            setStage({ kind: "moddable-preflight" });
+                        } else {
+                            declineModdable();
+                        }
+                    }}
+                />
+            )}
+
+            {stage.kind === "moddable-preflight" && (
+                <ModdablePreflightStage
+                    // git resolves `origin` from any subdirectory of the repo,
+                    // so the typed path works even when it's a build output dir.
+                    projectDir={localPath!}
+                    onResolved={(url) => {
+                        setRepositoryUrl(url);
+                        advance({ moddable: true, repositoryUrl: url });
                     }}
+                    onError={(msg) => setStage({ kind: "moddable-error", message: msg })}
+                />
+            )}
+
+            {stage.kind === "moddable-error" && (
+                <ModdableErrorStage
+                    message={stage.message}
+                    onContinueWithoutModdable={declineModdable}
+                    onExit={() => onDone({ kind: "cancel" })}
                 />
             )}
 
@@ -347,6 +431,7 @@ export function DecentralizeScreen({
                     signer={activeSigner!}
                     signerMode={signerMode!}
                     publishToPlayground={publishToPlayground === true}
+                    repositoryUrl={repositoryUrl}
                     onConfirm={() => setStage({ kind: "running" })}
                     onCancel={() => onDone({ kind: "cancel" })}
                 />
@@ -360,6 +445,7 @@ export function DecentralizeScreen({
                     mode={signerMode!}
                     userSigner={explicitSigner ?? sessionSigner}
                     publishToPlayground={publishToPlayground === true}
+                    repositoryUrl={repositoryUrl}
                     env={env}
                     onComplete={(outcome) => setStage({ kind: "done", outcome })}
                     onFailed={(message) => setStage({ kind: "error", message })}
@@ -473,6 +559,7 @@ function ConfirmStage({
     signer,
     signerMode,
     publishToPlayground,
+    repositoryUrl,
     onConfirm,
     onCancel,
 }: {
@@ -485,6 +572,8 @@ function ConfirmStage({
     signer: ResolvedSigner;
     signerMode: SignerMode;
     publishToPlayground: boolean;
+    /** Resolved public GitHub URL when moddable was accepted; null otherwise. */
+    repositoryUrl: string | null;
     onConfirm: () => void;
     onCancel: () => void;
 }) {
@@ -524,6 +613,13 @@ function ConfirmStage({
                     value={publishToPlayground ? "publish to apps tab" : "skip"}
                     tone={publishToPlayground ? "accent" : "muted"}
                 />
+                {source.kind === "path" && publishToPlayground && (
+                    <Row
+                        label="moddable"
+                        value={repositoryUrl ? `yes · ${repositoryUrl}` : "no"}
+                        tone={repositoryUrl ? "accent" : "muted"}
+                    />
+                )}
                 {availabilityNote && <Row label="note" value={availabilityNote} tone="warning" />}
                 {largeLocal && (
                     <Row
@@ -572,6 +668,7 @@ function RunningStage({
     mode,
     userSigner,
     publishToPlayground,
+    repositoryUrl,
     env,
     onComplete,
     onFailed,
@@ -582,6 +679,8 @@ function RunningStage({
     mode: SignerMode;
     userSigner: ResolvedSigner | null;
     publishToPlayground: boolean;
+    /** Preflighted public GitHub URL when moddable was accepted; null otherwise. */
+    repositoryUrl: string | null;
     env: Env;
     onComplete: (outcome: DecentralizeOutcome) => void;
     onFailed: (message: string) => void;
@@ -627,6 +726,7 @@ function RunningStage({
                     mode,
                     userSigner,
                     publishToPlayground,
+                    repositoryUrl,
                     env,
                     onEvent: (event) => {
                         switch (event.kind) {

src/commands/decentralize/index.ts

@@ -27,9 +27,10 @@
  * Headless flow runs when `--site` or `--path` is provided (preserves the
  * existing `dot decentralize --suri=//Bob` demo-service contract). Without
  * either, the command mounts an Ink TUI that prompts for source (URL or
- * local directory) → URL/path → signer → domain → publish? before kicking
- * off the same upload pipeline. The publish-to-playground step delegates to
- * deploy's `publishToPlayground` helper.
+ * local directory) → URL/path → signer → domain → publish? → moddable?
+ * (path mode only) before kicking off the same upload pipeline. The
+ * publish-to-playground step delegates to deploy's `publishToPlayground`
+ * helper.
  */
 
 import { Command, Option } from "commander";
@@ -48,6 +49,11 @@ import {
     type DecentralizeSource,
 } from "../../utils/decentralize/run.js";
 import { destroyConnection } from "../../utils/connection.js";
+import {
+    ensureGitInstalled,
+    ModdablePreflightError,
+    resolveRepositoryUrl,
+} from "../../utils/deploy/moddable.js";
 import type { SignerMode } from "../../utils/deploy/signerMode.js";
 import { onProcessShutdown } from "../../utils/process-guard.js";
 
@@ -63,6 +69,13 @@ interface DecentralizeOpts {
      * in headless" — i.e. opt-in publish.
      */
     playground?: boolean;
+    /**
+     * Record the path directory's public GitHub origin in the playground
+     * metadata so others can `playground mod` the app. Path mode only
+     * (`.conflicts("site")` — a mirrored URL has no git source) and requires
+     * `--playground` in headless mode. `undefined` ⇒ ask in the TUI.
+     */
+    moddable?: boolean;
 }
 
 export const decentralizeCommand = new Command("decentralize")
@@ -101,6 +114,13 @@ export const decentralizeCommand = new Command("decentralize")
         "After upload, also publish a minimal AppInfo entry to the playground registry " +
             "(visible in the playground-app's Apps tab). Off by default.",
     )
+    .addOption(
+        new Option(
+            "--moddable",
+            "Record the public GitHub origin of --path's repo so others can " +
+                "`playground mod` it. Requires --path and --playground. Off by default.",
+        ).conflicts("site"),
+    )
     .action(async (opts: DecentralizeOpts) =>
         runCliCommand("decentralize", { hardExit: true }, async () => {
             const env: Env = resolveLegacyEnv(opts.env);
@@ -130,6 +150,38 @@ async function runHeadless({
         // (prepareLocalDirectory is cheap and pure fs).
         if (opts.path) prepareLocalDirectory(opts.path);
 
+        // Moddable preflight, same fail-fast rationale: resolve the public
+        // GitHub origin (git walks up from the --path directory) before any
+        // signer/chain work. `ModdablePreflightError`'s headless message
+        // already names the fix, so it propagates as-is. `--site` is blocked
+        // by commander's `.conflicts()`, so `opts.path` is set here.
+        let repositoryUrl: string | null = null;
+        if (opts.moddable) {
+            if (opts.playground !== true) {
+                throw new Error(
+                    "--moddable requires --playground — the repo URL is recorded in the " +
+                        "playground metadata, which is only published with --playground.",
+                );
+            }
+            await ensureGitInstalled();
+            try {
+                repositoryUrl = await resolveRepositoryUrl({
+                    cwd: opts.path!,
+                    onLog: (line) => process.stdout.write(`  ${line}\n`),
+                });
+            } catch (err) {
+                // The headless message in moddable.ts names deploy's
+                // `--no-moddable` escape hatch, which this command doesn't
+                // have — use the surface-neutral copy + the right remedy.
+                if (err instanceof ModdablePreflightError) {
+                    throw new Error(
+                        `${err.interactiveMessage} Or omit --moddable to publish without source.`,
+                    );
+                }
+                throw err;
+            }
+        }
+
         signer = await withSpan("cli.decentralize.signer", "resolve signer", () =>
             resolveSigner({ suri: opts.suri }),
         );
@@ -166,6 +218,7 @@ async function runHeadless({
             mode,
             userSigner: signer,
             publishToPlayground: opts.playground === true,
+            repositoryUrl,
             env,
             onEvent: (ev) => {
                 switch (ev.kind) {
@@ -272,6 +325,7 @@ async function runInteractive({
                     explicitSigner: preflight.explicitSigner,
                     sessionSigner: preflight.sessionSigner,
                     initialPublishToPlayground: opts.playground === true ? true : null,
+                    initialModdable: opts.moddable === true ? true : null,
                     onDone: (result) => {
                         if (settled) return;
                         settled = true;