@noodleseed/one 0.155.0 → 0.156.0

package/README.md

@@ -58,13 +58,17 @@ Create and run a local project without a Noodle Seed account:
 npx @noodleseed/one@latest init my-noodle-app
 cd my-noodle-app
 npm install
+npm test
 npm run validate
-npm run dev
 ```
 
 The generated project contains a normal TypeScript entrypoint, tests, npm scripts, `noodle.json`, and
 project-local instructions for supported coding agents. It remains your project: edit it with your existing
 tools, commit it to your repository, and run it locally before deciding to deploy.
+The default SaaS starter is embedded-first and explicitly synthetic: its tests check a useful local result
+and invalid-input rejection without customer credentials or live backends. Bind the names in `.env.example`
+before `npm run dev`; wire the generated integration seams to your existing application before claiming
+customer authentication or saved business changes. `--template hello` needs no configuration.
 
 For frequent CLI use, you can install the same package globally:
 

package/dist/assistant-embed-django-tests.d.ts

@@ -0,0 +1,3 @@
+/** Tests ship with the Python profile and run through the customer's existing Django test runner. */
+export declare function djangoContractTests(): string;
+//# sourceMappingURL=assistant-embed-django-tests.d.ts.map

package/dist/assistant-embed-django-tests.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assistant-embed-django-tests.d.ts","sourceRoot":"","sources":["../src/assistant-embed-django-tests.ts"],"names":[],"mappings":"AAAA,qGAAqG;AACrG,wBAAgB,mBAAmB,IAAI,MAAM,CAyI5C"}

package/dist/assistant-embed-django-tests.js

@@ -0,0 +1,140 @@
+/** Tests ship with the Python profile and run through the customer's existing Django test runner. */
+export function djangoContractTests() {
+    return `import json
+from unittest.mock import Mock, patch
+
+import requests
+from django.test import Client, SimpleTestCase, override_settings
+
+
+@override_settings(
+    ROOT_URLCONF="noodle_assistant.urls", ALLOWED_HOSTS=["app.example"],
+    MIDDLEWARE=["django.middleware.csrf.CsrfViewMiddleware"],
+    PUBLIC_APP_ORIGIN="https://app.example", NOODLE_SERVICE_URL="https://cloud.example",
+    NOODLE_ASSISTANT_CLIENT_ID="synthetic-client", NOODLE_ASSISTANT_CLIENT_SECRET="synthetic-test-credential",
+)
+class AssistantSessionContractTests(SimpleTestCase):
+    """Synthetic route proof. Add real session/membership fixtures in the application's own suite."""
+
+    def setUp(self):
+        self.client = Client(enforce_csrf_checks=True)
+        self.csrf = "a" * 32
+        self.client.cookies["csrftoken"] = self.csrf
+        self.identity_patch = patch("noodle_assistant.views.authenticate_assistant_request", return_value=None)
+        self.authenticate = self.identity_patch.start()
+        self.addCleanup(self.identity_patch.stop)
+        self.exchange_patch = patch("noodle_assistant.views.requests.post")
+        self.exchange = self.exchange_patch.start()
+        self.addCleanup(self.exchange_patch.stop)
+        self.session = {
+            "token": "synthetic-session", "expiresAt": "2030-01-01T00:00:00Z",
+            "endpoints": {"turns": "https://cloud.example/turns", "toolConfirmations": "https://cloud.example/confirmations"},
+        }
+        upstream = Mock(status_code=201)
+        upstream.iter_content.return_value = [json.dumps(self.session).encode()]
+        self.upstream = upstream
+        self.exchange.return_value.__enter__.return_value = upstream
+
+    def post(self, body=None, **headers):
+        defaults = {"HTTP_HOST": "app.example", "HTTP_ORIGIN": "https://app.example", "HTTP_X_CSRFTOKEN": self.csrf}
+        defaults.update(headers)
+        return self.client.post("/api/assistant/session", json.dumps({} if body is None else body), content_type="application/json", secure=True, **defaults)
+
+    def signed_in(self):
+        self.authenticate.return_value = {
+            "user": {"id": "person-a", "tenant": "tenant-a", "scopes": ["tasks:read"]},
+            "routing": {"endpoints": {"customer_api": "https://tenant-a.example/api"}},
+        }
+
+    def test_signed_out_is_json_401_not_redirect(self):
+        response = self.post()
+        self.assertEqual(response.status_code, 401)
+        self.assertEqual(response.json()["code"], "authentication_required")
+        self.assertNotIn("Location", response)
+        self.assertEqual(response["Cache-Control"], "no-store")
+        self.exchange.assert_not_called()
+
+    def test_csrf_is_not_exempted(self):
+        self.assertEqual(self.post(HTTP_X_CSRFTOKEN="").status_code, 403)
+        self.authenticate.assert_not_called()
+        self.exchange.assert_not_called()
+
+    def test_wrong_origin_is_refused_before_identity_or_exchange(self):
+        self.assertEqual(self.post(HTTP_ORIGIN="https://attacker.example").status_code, 403)
+        self.authenticate.assert_not_called()
+        self.exchange.assert_not_called()
+
+    def test_form_content_type_is_refused(self):
+        response = self.client.post("/api/assistant/session", "{}", content_type="text/plain", secure=True,
+            HTTP_HOST="app.example", HTTP_ORIGIN="https://app.example", HTTP_X_CSRFTOKEN=self.csrf)
+        self.assertEqual(response.status_code, 415)
+        self.exchange.assert_not_called()
+
+    def test_browser_cannot_choose_identity_or_routes(self):
+        self.signed_in()
+        for body in ({"user": {"id": "person-b"}}, {"routing": {}}, {"claims": {"admin": True}},
+                     {"context": {"nested": {}}}, {"context": {"number": float("inf")}},
+                     {"context": {"number": 10 ** 1_000}}, {"context": {"text": "x" * 2_001}}):
+            with self.subTest(body_kind=next(iter(body))):
+                self.assertEqual(self.post(body).status_code, 400)
+        self.exchange.assert_not_called()
+
+    def test_body_limit(self):
+        self.signed_in()
+        self.assertEqual(self.post({"context": {"page": "x" * 16_384}}).status_code, 413)
+        self.exchange.assert_not_called()
+
+    def test_deep_json_is_refused_without_a_server_error(self):
+        self.signed_in()
+        nested = "[" * 3_000 + "0" + "]" * 3_000
+        response = self.client.post("/api/assistant/session", nested, content_type="application/json", secure=True,
+            HTTP_HOST="app.example", HTTP_ORIGIN="https://app.example", HTTP_X_CSRFTOKEN=self.csrf)
+        self.assertEqual(response.status_code, 400)
+        self.exchange.assert_not_called()
+        self.upstream.iter_content.return_value = [nested.encode()]
+        self.assertEqual(self.post().status_code, 502)
+        # Older supported Python parsers can exhaust recursion before reaching the byte limit.
+        with patch("noodle_assistant.views.json.loads", side_effect=RecursionError):
+            self.assertEqual(self.post().status_code, 400)
+        with patch("noodle_assistant.views.json.loads", side_effect=[{}, RecursionError()]):
+            self.assertEqual(self.post().status_code, 502)
+
+    def test_success_uses_backend_identity_without_forwarding_cookies(self):
+        self.signed_in()
+        response = self.post({"context": {"page": "tasks"}}, HTTP_AUTHORIZATION="Bearer synthetic-inbound")
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(response.json(), self.session)
+        self.assertEqual(response["Cache-Control"], "no-store")
+        sent = self.exchange.call_args.kwargs
+        self.assertEqual(sent["json"]["user"]["tenant"], "tenant-a")
+        self.assertEqual(sent["json"]["routing"], self.authenticate.return_value["routing"])
+        self.assertFalse(sent["allow_redirects"])
+        self.assertEqual(sent["timeout"], (3, 10))
+        self.assertNotIn("synthetic-inbound", str(sent))
+        self.assertNotIn("Cookie", sent["headers"])
+
+    def test_exchange_failure_is_sanitized(self):
+        self.signed_in()
+        self.exchange.side_effect = requests.Timeout("private upstream details")
+        response = self.post()
+        self.assertEqual(response.status_code, 502)
+        self.assertNotIn(b"private", response.content)
+        self.exchange.assert_called_once()
+
+    def test_redirect_and_html_are_not_forwarded(self):
+        self.signed_in()
+        self.upstream.status_code = 302
+        self.assertEqual(self.post().status_code, 502)
+        self.upstream.status_code = 200
+        self.upstream.iter_content.return_value = [b"<html>private upstream details</html>"]
+        self.assertEqual(self.post().status_code, 502)
+
+    def test_missing_configuration_and_identity_failure_are_not_signed_out(self):
+        with override_settings(NOODLE_ASSISTANT_CLIENT_SECRET=""):
+            self.assertEqual(self.post().status_code, 503)
+        self.authenticate.side_effect = RuntimeError("private identity failure")
+        self.assertEqual(self.post().status_code, 503)
+        self.exchange.assert_not_called()
+`;
+}
+//# sourceMappingURL=assistant-embed-django-tests.js.map

package/dist/assistant-embed-django-tests.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assistant-embed-django-tests.js","sourceRoot":"","sources":["../src/assistant-embed-django-tests.ts"],"names":[],"mappings":"AAAA,qGAAqG;AACrG,MAAM,UAAU,mBAAmB;IACjC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuIR,CAAC;AACF,CAAC"}

package/dist/assistant-embed-django.d.ts

@@ -0,0 +1,4 @@
+/** Python infrastructure is delivered as reviewed source, not a new runtime package or identity bridge. */
+export declare function djangoEmbedFiles(): Record<string, string>;
+export declare function djangoIntegrationGuide(): string;
+//# sourceMappingURL=assistant-embed-django.d.ts.map

package/dist/assistant-embed-django.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assistant-embed-django.d.ts","sourceRoot":"","sources":["../src/assistant-embed-django.ts"],"names":[],"mappings":"AAGA,2GAA2G;AAC3G,wBAAgB,gBAAgB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAuMzD;AAED,wBAAgB,sBAAsB,IAAI,MAAM,CAsD/C"}

package/dist/assistant-embed-django.js

@@ -0,0 +1,259 @@
+import { djangoContractTests } from './assistant-embed-django-tests.js';
+import { vueEmbedFiles } from './assistant-embed-vue.js';
+/** Python infrastructure is delivered as reviewed source, not a new runtime package or identity bridge. */
+export function djangoEmbedFiles() {
+    return {
+        'noodle_assistant/__init__.py': '',
+        'noodle_assistant/auth.py': `from django.http import HttpRequest
+
+from .contracts import AssistantIdentity
+
+
+def authenticate_assistant_request(request: HttpRequest) -> AssistantIdentity | None:
+    """The sole backend seam: use the existing session and server-owned membership lookup."""
+    # Return None when signed out. Derive user, tenant, roles, scopes and routing server-side.
+    # Never trust browser JSON, a raw cookie, or a user-selected URL as verified identity/routing.
+    # Do not redirect or log cookies/credentials. An unavailable identity service should raise.
+    return None
+`,
+        'noodle_assistant/contracts.py': `from typing import TypedDict
+
+
+class RequiredUser(TypedDict):
+    id: str
+
+
+class AssistantUser(RequiredUser, total=False):
+    email: str
+    name: str
+    tenant: str
+    roles: list[str]
+    scopes: list[str]
+
+
+class RequiredIdentity(TypedDict):
+    user: AssistantUser
+
+
+class AssistantIdentity(RequiredIdentity, total=False):
+    claims: dict[str, str | int | float | bool | None]
+    preferences: dict[str, str]
+    routing: dict[str, dict[str, str]]
+`,
+        'noodle_assistant/views.py': `import json
+import math
+from urllib.parse import urlsplit
+
+import requests
+from django.conf import settings
+from django.http import JsonResponse
+from django.views.decorators.csrf import csrf_protect
+
+from .auth import authenticate_assistant_request
+
+MAX_BODY_BYTES = 16 * 1024
+MAX_RESPONSE_BYTES = 256 * 1024
+
+
+def failure(status, code, message):
+    response = JsonResponse({"code": code, "error": message}, status=status)
+    response["Cache-Control"] = "no-store"
+    return response
+
+
+def safe_origin(value):
+    if not isinstance(value, str) or any(ord(char) <= 32 or ord(char) == 127 for char in value):
+        return False
+    try:
+        url = urlsplit(value)
+        return (
+            bool(url.hostname) and "*" not in value and url.username is None
+            and url.password is None and url.port != 0
+            and value == f"{url.scheme}://{url.netloc}"
+            and (url.scheme == "https" or (
+                url.scheme == "http" and url.hostname in ("localhost", "127.0.0.1", "::1")
+            ))
+        )
+    except ValueError:
+        return False
+
+
+def configuration():
+    names = ("PUBLIC_APP_ORIGIN", "NOODLE_SERVICE_URL", "NOODLE_ASSISTANT_CLIENT_ID", "NOODLE_ASSISTANT_CLIENT_SECRET")
+    values = [getattr(settings, name, None) for name in names]
+    if not all(isinstance(value, str) and value.strip() for value in values):
+        return None
+    origin, service, client_id, client_secret = values
+    service = service.rstrip("/")
+    if not safe_origin(origin) or not safe_origin(service) or ":" in client_id:
+        return None
+    return origin, service, client_id, client_secret
+
+
+def finite_number(value):
+    try:
+        return isinstance(value, (int, float)) and math.isfinite(value)
+    except OverflowError:
+        return False
+
+
+def valid_context(value):
+    return isinstance(value, dict) and len(value) <= 32 and all(
+        isinstance(key, str) and len(key) <= 80 and (
+            item is None or isinstance(item, bool)
+            or finite_number(item)
+            or (isinstance(item, str) and len(item) <= 2_000)
+        ) for key, item in value.items()
+    )
+
+
+@csrf_protect
+def assistant_session(request):
+    """Same-origin JSON endpoint. Keep Django's CsrfViewMiddleware enabled."""
+    if request.method != "POST":
+        response = failure(405, "method_not_allowed", "POST required")
+        response["Allow"] = "POST"
+        return response
+    config = configuration()
+    if config is None:
+        return failure(503, "assistant_not_configured", "assistant is not configured")
+    origin, service, client_id, client_secret = config
+    if request.headers.get("Origin") != origin:
+        return failure(403, "origin_not_allowed", "origin is not allowed")
+    if request.content_type != "application/json":
+        return failure(415, "unsupported_media_type", "application/json required")
+    try:
+        identity = authenticate_assistant_request(request)
+    except Exception:
+        return failure(503, "authentication_unavailable", "application authentication is unavailable")
+    if identity is None:
+        return failure(401, "authentication_required", "authentication required")
+    if not isinstance(identity, dict) or not isinstance(identity.get("user"), dict):
+        return failure(503, "authentication_unavailable", "application authentication is unavailable")
+    user_id = identity["user"].get("id")
+    if not isinstance(user_id, str) or not 1 <= len(user_id) <= 240:
+        return failure(503, "authentication_unavailable", "application authentication is unavailable")
+    try:
+        raw = request.read(MAX_BODY_BYTES + 1)
+        if len(raw) > MAX_BODY_BYTES:
+            return failure(413, "request_too_large", "request must not exceed 16 KiB")
+        body = json.loads(raw)
+    except (ValueError, OSError, RecursionError):
+        return failure(400, "invalid_request", "invalid JSON request")
+    if not isinstance(body, dict) or set(body) - {"context"}:
+        return failure(400, "invalid_request", "invalid request body")
+    if "context" in body and not valid_context(body["context"]):
+        return failure(400, "invalid_request", "invalid context")
+    payload = {"origin": origin, "user": identity["user"]}
+    for key in ("claims", "preferences", "routing"):
+        if key in identity:
+            payload[key] = identity[key]
+    if "context" in body:
+        payload["context"] = body["context"]
+    try:
+        # No redirects or retries; inbound cookies/bearers never reach the Noodle exchange.
+        with requests.post(
+            f"{service}/v1/assistant/sessions", auth=(client_id, client_secret),
+            headers={"Accept": "application/json"}, json=payload,
+            timeout=(3, 10), allow_redirects=False, stream=True,
+        ) as upstream:
+            if upstream.status_code not in (200, 201):
+                return failure(502, "session_exchange_failed", "assistant session exchange failed")
+            data = bytearray()
+            for chunk in upstream.iter_content(chunk_size=16 * 1024):
+                data.extend(chunk)
+                if len(data) > MAX_RESPONSE_BYTES:
+                    return failure(502, "session_exchange_failed", "assistant session exchange failed")
+            session = json.loads(data)
+            if not isinstance(session, dict) or not isinstance(session.get("token"), str) or not isinstance(session.get("endpoints"), dict):
+                return failure(502, "session_exchange_failed", "assistant session exchange failed")
+    except (requests.RequestException, ValueError, RecursionError):
+        return failure(502, "session_exchange_failed", "assistant session exchange failed")
+    response = JsonResponse(session)
+    response["Cache-Control"] = "no-store"
+    return response
+`,
+        'noodle_assistant/urls.py': `from django.urls import path
+
+from .views import assistant_session
+
+urlpatterns = [path("api/assistant/session", assistant_session, name="noodle-assistant-session")]
+`,
+        'noodle_assistant/tests.py': djangoContractTests(),
+        'noodle_assistant/settings.example.py': `# Merge these names into existing Django settings; use the application's secret/config loader.
+# Never copy real credentials into source or expose them to the Vue build.
+import os
+
+NOODLE_SERVICE_URL = os.environ.get("NOODLE_SERVICE_URL")
+NOODLE_ASSISTANT_CLIENT_ID = os.environ.get("NOODLE_ASSISTANT_CLIENT_ID")
+NOODLE_ASSISTANT_CLIENT_SECRET = os.environ.get("NOODLE_ASSISTANT_CLIENT_SECRET")
+PUBLIC_APP_ORIGIN = os.environ.get("PUBLIC_APP_ORIGIN")
+# Keep django.middleware.csrf.CsrfViewMiddleware and existing authentication middleware enabled.
+# Root URL configuration: path("", include("noodle_assistant.urls"))
+`,
+        '.env.noodle-host.example': `# Backend settings only. Never copy these values into VITE_* or another browser-prefixed variable.
+NOODLE_SERVICE_URL=https://cloud.noodleseed.dev
+NOODLE_ASSISTANT_CLIENT_ID=
+NOODLE_ASSISTANT_CLIENT_SECRET=
+PUBLIC_APP_ORIGIN=http://localhost:5173
+`,
+        ...vueEmbedFiles(),
+        'NOODLE-INTEGRATION.md': djangoIntegrationGuide(),
+    };
+}
+export function djangoIntegrationGuide() {
+    return `# Django/Vue application integration
+
+This profile is authenticated only. The existing Django application owns identity, membership and CSRF;
+Vue stays a static frontend. Noodle authoring remains TypeScript in its own project. No Node production
+server, new login system or direct database connector is introduced.
+
+## Install and adapt
+
+1. Use the existing Python environment and package manager to add requests. The profile is qualified on
+   Django 5.2 and 6.1; use a Python version supported by your Django release. It does not replace application
+   settings, middleware or URL configuration. Other versions require your own validation.
+2. Include \`noodle_assistant.urls\` at the application root. Map the four names in
+   \`noodle_assistant/settings.example.py\` with your existing server-side config loader.
+3. Implement only \`authenticate_assistant_request\` in \`noodle_assistant/auth.py\`: return None when signed
+   out, otherwise verified user/tenant/scopes, optional claims/preferences and membership-derived routing.
+   Keep actual business functions and authorization in the application; never trust browser identity fields.
+4. Install a compatible \`@noodleseed/assistant\` using the Vue application's existing package manager.
+   Render \`NoodleAssistant.vue\` inside the signed-in application with a stable user/tenant \`principalKey\`
+   and the current \`csrfToken\` from your existing CSRF bootstrap. Change the key on account changes.
+5. The wrapper sets the element's fetch property before mounting, adding \`X-CSRFToken\` only to the exact
+   same-origin session POST. It never sends that header to the Noodle service. Keep Django's normal CSRF
+   middleware. If your application uses a custom header name, adapt that one name with a regression test.
+6. Route \`/api/assistant/session\` through the Vue page's public origin to Django. Do not enable cross-origin
+   cookies or widen trusted origins to make a split infrastructure deployment work.
+
+The wrapper creates the Web Component directly, so Vue needs no custom-element compiler configuration.
+For CSRF tokens stored in HttpOnly cookies or server sessions, reuse the application's existing masked-token
+endpoint/DOM data. Do not expose an application session cookie or disable CSRF to make the test pass.
+
+## Verify
+
+- Run \`python manage.py test noodle_assistant\`: generated tests enforce CSRF and exercise the real view
+  using synthetic identity/exchange fixtures. A signed-out request with a valid CSRF token returns JSON 401;
+  an invalid/missing CSRF token is correctly refused by Django before the view.
+- Run \`vitest run test/noodle-assistant-transport.test.ts\` using the existing frontend test setup (add
+  Vitest as a dev dependency if absent), then build the existing Vue application.
+- Run \`noodle assistant embed --framework django-vue --check --json\` with host settings exported. It
+  reports static evidence only, not that Django imported settings or proxy rules are correct.
+- Add actual signed-out, tenant-A, tenant-B and authorized identity fixtures to the existing test harness;
+  exercise one sandbox read and confirmed action. Verify the real browser's CSRF, CSP, streaming and App frame.
+
+Keep the service in CSP connect-src and frame-src. Missing sandbox credentials, identities or permission
+remain unverified. Generated tests do not prove the customer's session function or production readiness.
+
+## Updates
+
+Preview with \`noodle assistant embed --framework django-vue --dry-run --json\`. Reruns create missing files
+and preserve modified code. Review conflicts; never use --force to erase an existing login implementation.
+These files are customer-owned after installation. Keep settings, secret values and business logic during
+upgrades and rerun the contract and application acceptance tests before deployment.
+
+Guide: https://docs.noodleseed.dev/docs/guides/embedded-assistant-django-vue
+`;
+}
+//# sourceMappingURL=assistant-embed-django.js.map

package/dist/assistant-embed-django.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assistant-embed-django.js","sourceRoot":"","sources":["../src/assistant-embed-django.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AACxE,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAEzD,2GAA2G;AAC3G,MAAM,UAAU,gBAAgB;IAC9B,OAAO;QACL,8BAA8B,EAAE,EAAE;QAClC,0BAA0B,EAAE;;;;;;;;;;;CAW/B;QACG,+BAA+B,EAAE;;;;;;;;;;;;;;;;;;;;;;;CAuBpC;QACG,2BAA2B,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoIhC;QACG,0BAA0B,EAAE;;;;;CAK/B;QACG,2BAA2B,EAAE,mBAAmB,EAAE;QAClD,sCAAsC,EAAE;;;;;;;;;;CAU3C;QACG,0BAA0B,EAAE;;;;;CAK/B;QACG,GAAG,aAAa,EAAE;QAClB,uBAAuB,EAAE,sBAAsB,EAAE;KAClD,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,sBAAsB;IACpC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoDR,CAAC;AACF,CAAC"}

package/dist/assistant-embed-installation.d.ts

@@ -0,0 +1,29 @@
+import type { EmbedFramework, EmbedSurface } from './assistant-embed-scaffold-template.js';
+export interface EmbedFileAction {
+    readonly path: string;
+    readonly action: 'created' | 'unchanged' | 'skipped' | 'overwritten';
+    readonly sha256: string;
+    readonly content?: string;
+}
+/** Inspect every fixed output before writing any of them; do not follow customer symlinks. */
+export declare function prepareEmbedInstallation(dir: string, contents: Readonly<Record<string, string>>, options: {
+    readonly force: boolean;
+    readonly dryRun: boolean;
+}): readonly EmbedFileAction[];
+/** Include instruction outputs in the same pre-write boundary as generated application files. */
+export declare function assertEmbedOutputPaths(dir: string, paths: readonly string[]): void;
+export declare function applyEmbedInstallation(dir: string, contents: Readonly<Record<string, string>>, files: readonly EmbedFileAction[]): void;
+/** Tool-facing recipe metadata describes installed assets, never a parallel authoring language. */
+export declare function embedRecipe(framework: EmbedFramework, surface: EmbedSurface, files: readonly EmbedFileAction[]): {
+    id: string;
+    version: number;
+    fingerprint: string;
+    appliesTo: string[];
+    doesNotApplyWhen: string[];
+    dependencies: string[];
+    applicationSeams: string[];
+    ownership: string;
+    verification: string[];
+};
+export declare function embedNextSteps(surface: EmbedSurface, framework?: EmbedFramework): readonly string[];
+//# sourceMappingURL=assistant-embed-installation.d.ts.map

package/dist/assistant-embed-installation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assistant-embed-installation.d.ts","sourceRoot":"","sources":["../src/assistant-embed-installation.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,wCAAwC,CAAC;AAE3F,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,SAAS,GAAG,aAAa,CAAC;IACrE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAMD,8FAA8F;AAC9F,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAC1C,OAAO,EAAE;IAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GAC7D,SAAS,eAAe,EAAE,CAe5B;AAED,iGAAiG;AACjG,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAUlF;AAED,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAC1C,KAAK,EAAE,SAAS,eAAe,EAAE,GAChC,IAAI,CAiBN;AAED,mGAAmG;AACnG,wBAAgB,WAAW,CACzB,SAAS,EAAE,cAAc,EACzB,OAAO,EAAE,YAAY,EACrB,KAAK,EAAE,SAAS,eAAe,EAAE;;;;;;;;;;EAwClC;AAED,wBAAgB,cAAc,CAC5B,OAAO,EAAE,YAAY,EACrB,SAAS,GAAE,cAAyB,GACnC,SAAS,MAAM,EAAE,CAiCnB"}

package/dist/assistant-embed-installation.js

@@ -0,0 +1,124 @@
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { embedCheckCommand } from './assistant-embed-profile.js';
+function hash(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+/** Inspect every fixed output before writing any of them; do not follow customer symlinks. */
+export function prepareEmbedInstallation(dir, contents, options) {
+    assertEmbedOutputPaths(dir, Object.keys(contents));
+    return Object.entries(contents).map(([path, content]) => {
+        const full = join(dir, path);
+        const existing = existsSync(full) ? readFileSync(full, 'utf8') : undefined;
+        const action = existing === content
+            ? 'unchanged'
+            : existing === undefined
+                ? 'created'
+                : options.force
+                    ? 'overwritten'
+                    : 'skipped';
+        return { path, action, sha256: hash(content), ...(options.dryRun ? { content } : {}) };
+    });
+}
+/** Include instruction outputs in the same pre-write boundary as generated application files. */
+export function assertEmbedOutputPaths(dir, paths) {
+    for (const path of paths) {
+        let current = dir;
+        for (const segment of ['', ...path.split('/')]) {
+            current = join(current, segment);
+            if (lstatSync(current, { throwIfNoEntry: false })?.isSymbolicLink()) {
+                throw new Error('assistant_embed_unsafe_path');
+            }
+        }
+    }
+}
+export function applyEmbedInstallation(dir, contents, files) {
+    assertEmbedOutputPaths(dir, files.map((file) => file.path));
+    for (const file of files) {
+        if (file.action === 'unchanged' || file.action === 'skipped')
+            continue;
+        const full = join(dir, file.path);
+        mkdirSync(dirname(full), { recursive: true });
+        const content = contents[file.path];
+        if (content === undefined || hash(content) !== file.sha256) {
+            throw new Error('assistant_embed_plan_changed');
+        }
+        writeFileSync(full, content, {
+            flag: file.action === 'created' ? 'wx' : 'w',
+        });
+    }
+}
+/** Tool-facing recipe metadata describes installed assets, never a parallel authoring language. */
+export function embedRecipe(framework, surface, files) {
+    return {
+        id: `${framework}-${surface}`,
+        version: 1,
+        fingerprint: hash(JSON.stringify(files.map(({ path, sha256 }) => ({ path, sha256 })))),
+        appliesTo: [
+            'Existing application with the requested website surface',
+            'One canonical TypeScript Noodle application',
+        ],
+        doesNotApplyWhen: [
+            'Native/mobile host',
+            'No authorized access to the customer application',
+            'Unresolved identity or tenant authorization',
+        ],
+        dependencies: framework === 'django-vue'
+            ? ['@noodleseed/assistant', 'Django', 'requests', 'vue']
+            : ['@noodleseed/assistant'],
+        applicationSeams: surface === 'public'
+            ? ['Public embed configuration', 'Application mount', 'Existing business operations']
+            : [
+                framework === 'django-vue'
+                    ? 'authenticate_assistant_request'
+                    : 'authenticateAssistantRequest',
+                'Backend-owned tenant and permission mapping',
+                ...(surface === 'mixed' ? ['Existing login transaction and signInTicket handoff'] : []),
+                'Application mount',
+                'Existing business operations',
+            ],
+        ownership: 'Customer-owned source after installation; reruns preserve modified files unless --force is explicitly selected.',
+        verification: [
+            'Host build',
+            'Application identity/tenant negative tests',
+            'Representative sandbox workflow',
+            'Browser turn and linked App',
+        ],
+    };
+}
+export function embedNextSteps(surface, framework = 'nextjs') {
+    if (framework === 'django-vue')
+        return [
+            'Reuse the Django and Vue package managers; add requests and a compatible @noodleseed/assistant.',
+            'Include noodle_assistant.urls and bind the server-only names in noodle_assistant/settings.example.py.',
+            'Implement authenticate_assistant_request in noodle_assistant/auth.py using existing session and membership checks.',
+            'Render src/components/NoodleAssistant.vue with principalKey and the existing application csrfToken.',
+            'Keep normal Django CSRF middleware; route the session endpoint through the frontend origin.',
+            'Run python manage.py test noodle_assistant, the generated frontend transport tests, and the existing Vue build.',
+            'Run noodle assistant embed --framework django-vue --check --json with settings exported; finish the independent checks in NOODLE-INTEGRATION.md.',
+            'Integration remains unverified until actual application identity, tenant and browser checks pass.',
+        ];
+    return [
+        'Install a compatible @noodleseed/assistant version with the application package manager.',
+        ...(surface === 'public'
+            ? [
+                'Set NEXT_PUBLIC_NOODLE_EMBED_ID and NEXT_PUBLIC_NOODLE_SERVICE_URL from the selected local or hosted deployment.',
+            ]
+            : [
+                'Configure backend-only credentials from noodle assistant clients create for an explicitly authorized target.',
+                'Implement authenticateAssistantRequest in lib/noodle-assistant-auth.ts using the existing session and membership checks.',
+            ]),
+        ...(surface === 'mixed'
+            ? [
+                'Bind onSignInRequested to the existing backend login transaction; verify signInTicket continuation.',
+            ]
+            : []),
+        surface === 'public'
+            ? 'Render AssistantWidget in the selected application layout.'
+            : 'Render AssistantWidget with a stable user/tenant principalKey; change it on account changes (null for an anonymous mixed surface).',
+        `Run ${embedCheckCommand(surface)} with the host environment exported, then the independent checks in NOODLE-INTEGRATION.md.`,
+        'Application integration remains unverified until those checks run; installation does not authorize deployment or live writes.',
+    ];
+}
+//# sourceMappingURL=assistant-embed-installation.js.map

package/dist/assistant-embed-installation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assistant-embed-installation.js","sourceRoot":"","sources":["../src/assistant-embed-installation.ts"],"names":[],"mappings":"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"}

package/dist/assistant-embed-profile.d.ts

@@ -0,0 +1,8 @@
+import type { EmbedSurface } from './assistant-embed-scaffold-template.js';
+/** Reuse preflight's explicit env aliases instead of duplicating browser configuration. */
+export declare function embedCheckCommand(surface: EmbedSurface): string;
+/** Public mounting uses the existing hosted session source, never a customer proxy route. */
+export declare function publicEmbedFiles(surface: 'public' | 'mixed'): Record<string, string>;
+/** One customer handoff accompanies every installed profile and its machine-readable plan. */
+export declare function embedIntegrationGuide(surface: EmbedSurface): string;
+//# sourceMappingURL=assistant-embed-profile.d.ts.map

package/dist/assistant-embed-profile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assistant-embed-profile.d.ts","sourceRoot":"","sources":["../src/assistant-embed-profile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wCAAwC,CAAC;AAG3E,2FAA2F;AAC3F,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAQ/D;AAED,6FAA6F;AAC7F,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA4EpF;AAED,8FAA8F;AAC9F,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAiEnE"}