Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

refactor: build each Tailscale setup step in its own function (#12361)

[._.]/ Adam Eivy4ca8632e28d2
diff --git a/server/lib/networkExposure.js b/server/lib/networkExposure.js
index 987fc97493..8895ab9a6d 100644
--- a/server/lib/networkExposure.js
+++ b/server/lib/networkExposure.js
@@ -125,13 +125,7 @@ const tailscaleStatusUnknown = (tailscale) => [
'tailscale-parse-error',
].includes(tailscale?.reason);
-/**
- * Ordered, side-effect-free remote-access walkthrough shared by the API and
- * the setup/update CLI. `status` is one of complete/action/blocked/unknown;
- * callers render the same facts in their own medium and execute actions only
- * after an explicit user click (the CLI provisioner is invoked separately).
- */
-export function buildNetworkSetupGuide(network = {}, tailscale = {}) {
+function deriveSetupFacts(network, tailscale) {
const cert = network?.cert ?? {};
const port = Number(network?.bind?.port) || PORTS.API;
const currentDnsName = getTailscaleCertHostname({
@@ -144,7 +138,7 @@ export function buildNetworkSetupGuide(network = {}, tailscale = {}) {
const accessHost = currentDnsName || provisionedHost;
const installed = tailscale?.available === true;
const running = tailscale?.running === true;
- const statusUnknown = tailscaleStatusUnknown(tailscale);
+ const sandboxed = tailscale?.sandboxed === true;
const magicDnsReady = running && Boolean(currentDnsName);
const trustedCertProvisioned = cert?.provisioned === true
&& cert?.provisionedMode === 'tailscale';
@@ -155,96 +149,149 @@ export function buildNetworkSetupGuide(network = {}, tailscale = {}) {
const trustedHttpsActive = network?.httpsEnabled === true
&& cert?.mode === 'tailscale'
&& canActivate;
- const trustedUrl = trustedHttpsActive && accessHost
- ? `https://${accessHost}:${port}`
- : null;
const pendingTrustedUrl = canActivate && accessHost
? `https://${accessHost}:${port}`
: null;
+ return {
+ currentDnsName,
+ provisionedHost,
+ installed,
+ running,
+ sandboxed,
+ state: tailscale?.state,
+ statusUnknown: tailscaleStatusUnknown(tailscale),
+ magicDnsReady,
+ trustedCertProvisioned,
+ certMatchesCurrentHost,
+ canActivate,
+ trustedHttpsActive,
+ trustedUrl: trustedHttpsActive ? pendingTrustedUrl : null,
+ pendingTrustedUrl,
+ canProvision: magicDnsReady && installed && !sandboxed,
+ };
+}
- const writableCli = installed && tailscale?.sandboxed !== true;
- const canProvision = magicDnsReady && writableCli;
+const installStep = ({ installed }) => (installed
+ ? setupStep('tailscale-install', 'Install Tailscale', 'complete', 'The Tailscale CLI is installed on this machine.')
+ : setupStep(
+ 'tailscale-install',
+ 'Install Tailscale',
+ 'action',
+ 'Install Tailscale on the PortOS host so other devices can reach it privately.',
+ { type: 'external', label: 'Install Tailscale', url: TAILSCALE_DOWNLOAD_URL },
+ ));
- const steps = [
- setupStep(
- 'tailscale-install',
- 'Install Tailscale',
- installed ? 'complete' : 'action',
- installed
- ? 'The Tailscale CLI is installed on this machine.'
- : 'Install Tailscale on the PortOS host so other devices can reach it privately.',
- installed ? null : { type: 'external', label: 'Install Tailscale', url: TAILSCALE_DOWNLOAD_URL },
- ),
- setupStep(
+function connectStep({ installed, running, statusUnknown, state }) {
+ const title = 'Connect this machine';
+ if (running) return setupStep('tailscale-connect', title, 'complete', 'This machine is connected to its tailnet.');
+ if (!installed) return setupStep('tailscale-connect', title, 'blocked', 'Install Tailscale before connecting this machine.');
+ const help = { type: 'external', label: 'Tailscale connection help', url: TAILSCALE_DOWNLOAD_URL };
+ if (statusUnknown) {
+ return setupStep(
'tailscale-connect',
- 'Connect this machine',
- running ? 'complete' : installed && statusUnknown ? 'unknown' : installed ? 'action' : 'blocked',
- running
- ? 'This machine is connected to its tailnet.'
- : statusUnknown
- ? 'PortOS could not read Tailscale status. Open Tailscale and confirm this machine is connected.'
- : installed
- ? `Tailscale is ${tailscale?.state || 'not connected'}. Open the Tailscale app and sign in.`
- : 'Install Tailscale before connecting this machine.',
- installed && !running
- ? { type: 'external', label: 'Tailscale connection help', url: TAILSCALE_DOWNLOAD_URL }
- : null,
- ),
- setupStep(
+ title,
+ 'unknown',
+ 'PortOS could not read Tailscale status. Open Tailscale and confirm this machine is connected.',
+ help,
+ );
+ }
+ return setupStep(
+ 'tailscale-connect',
+ title,
+ 'action',
+ `Tailscale is ${state || 'not connected'}. Open the Tailscale app and sign in.`,
+ help,
+ );
+}
+
+function magicDnsStep({ running, magicDnsReady, currentDnsName }) {
+ const title = 'Enable MagicDNS';
+ if (magicDnsReady) return setupStep('magic-dns', title, 'complete', `MagicDNS assigned ${currentDnsName}.`);
+ if (running) {
+ return setupStep(
'magic-dns',
- 'Enable MagicDNS',
- magicDnsReady ? 'complete' : running ? 'action' : 'blocked',
- magicDnsReady
- ? `MagicDNS assigned ${currentDnsName}.`
- : running
- ? 'Enable MagicDNS in the tailnet DNS admin so this machine gets a stable .ts.net name.'
- : 'Connect Tailscale before checking the MagicDNS name.',
- running && !magicDnsReady
- ? { type: 'external', label: 'Open Tailscale DNS admin', url: TAILSCALE_DNS_ADMIN_URL }
- : null,
- ),
- setupStep(
- 'https-cert',
- 'Provision a trusted HTTPS certificate',
- certMatchesCurrentHost
- ? 'complete'
- : canProvision || (magicDnsReady && tailscale?.sandboxed === true)
- ? 'action'
- : 'blocked',
- certMatchesCurrentHost
- ? `A Tailscale certificate is installed for ${provisionedHost}.`
- : tailscale?.sandboxed
- ? 'The macOS App Store CLI cannot write PortOS certificate files. Install the writable CLI with `brew install tailscale`, then retry.'
- : trustedCertProvisioned && currentDnsName && provisionedHost !== currentDnsName
- ? `The installed certificate is for ${provisionedHost}; reprovision it for ${currentDnsName}.`
- : canProvision
- ? 'Enable HTTPS Certificates in the Tailscale DNS admin, then let PortOS fetch the certificate automatically.'
- : 'Complete the Tailscale and MagicDNS steps first.',
- certMatchesCurrentHost
- ? null
- : magicDnsReady && tailscale?.sandboxed
- ? { type: 'command', label: 'Install writable CLI', command: 'brew install tailscale' }
- : canProvision && !certMatchesCurrentHost
- ? { type: 'provision-cert', label: 'Enable HTTPS', adminUrl: TAILSCALE_DNS_ADMIN_URL }
- : null,
- ),
- setupStep(
- 'activate-https',
- 'Launch PortOS on its trusted URL',
- trustedHttpsActive ? 'complete' : canActivate ? 'action' : 'blocked',
- trustedHttpsActive
- ? `PortOS is live at ${trustedUrl}.`
- : canActivate
- ? `Restart PortOS, then open ${pendingTrustedUrl}.`
- : certMatchesCurrentHost
- ? 'Connect Tailscale and confirm its current MagicDNS name before launching the trusted URL.'
- : 'Provision the trusted certificate before switching the listener to HTTPS.',
- canActivate && !trustedHttpsActive
- ? { type: 'restart', label: 'Restart PortOS', targetUrl: pendingTrustedUrl }
- : trustedHttpsActive
- ? { type: 'external', label: 'Open PortOS', url: trustedUrl }
- : null,
- ),
+ title,
+ 'action',
+ 'Enable MagicDNS in the tailnet DNS admin so this machine gets a stable .ts.net name.',
+ { type: 'external', label: 'Open Tailscale DNS admin', url: TAILSCALE_DNS_ADMIN_URL },
+ );
+ }
+ return setupStep('magic-dns', title, 'blocked', 'Connect Tailscale before checking the MagicDNS name.');
+}
+
+function certStep({
+ certMatchesCurrentHost, provisionedHost, sandboxed, magicDnsReady,
+ trustedCertProvisioned, currentDnsName, canProvision,
+}) {
+ const id = 'https-cert';
+ const title = 'Provision a trusted HTTPS certificate';
+ if (certMatchesCurrentHost) {
+ return setupStep(id, title, 'complete', `A Tailscale certificate is installed for ${provisionedHost}.`);
+ }
+ if (sandboxed) {
+ return setupStep(
+ id,
+ title,
+ magicDnsReady ? 'action' : 'blocked',
+ 'The macOS App Store CLI cannot write PortOS certificate files. Install the writable CLI with `brew install tailscale`, then retry.',
+ magicDnsReady ? { type: 'command', label: 'Install writable CLI', command: 'brew install tailscale' } : null,
+ );
+ }
+ const status = canProvision ? 'action' : 'blocked';
+ const action = canProvision
+ ? { type: 'provision-cert', label: 'Enable HTTPS', adminUrl: TAILSCALE_DNS_ADMIN_URL }
+ : null;
+ if (trustedCertProvisioned && currentDnsName && provisionedHost !== currentDnsName) {
+ return setupStep(id, title, status, `The installed certificate is for ${provisionedHost}; reprovision it for ${currentDnsName}.`, action);
+ }
+ if (canProvision) {
+ return setupStep(id, title, status, 'Enable HTTPS Certificates in the Tailscale DNS admin, then let PortOS fetch the certificate automatically.', action);
+ }
+ return setupStep(id, title, status, 'Complete the Tailscale and MagicDNS steps first.', action);
+}
+
+function activateStep({
+ trustedHttpsActive, canActivate, certMatchesCurrentHost, trustedUrl, pendingTrustedUrl,
+}) {
+ const id = 'activate-https';
+ const title = 'Launch PortOS on its trusted URL';
+ if (trustedHttpsActive) {
+ return setupStep(id, title, 'complete', `PortOS is live at ${trustedUrl}.`, { type: 'external', label: 'Open PortOS', url: trustedUrl });
+ }
+ if (canActivate) {
+ return setupStep(
+ id,
+ title,
+ 'action',
+ `Restart PortOS, then open ${pendingTrustedUrl}.`,
+ { type: 'restart', label: 'Restart PortOS', targetUrl: pendingTrustedUrl },
+ );
+ }
+ return setupStep(
+ id,
+ title,
+ 'blocked',
+ certMatchesCurrentHost
+ ? 'Connect Tailscale and confirm its current MagicDNS name before launching the trusted URL.'
+ : 'Provision the trusted certificate before switching the listener to HTTPS.',
+ );
+}
+
+/**
+ * Ordered, side-effect-free remote-access walkthrough shared by the API and
+ * the setup/update CLI. `status` is one of complete/action/blocked/unknown;
+ * callers render the same facts in their own medium and execute actions only
+ * after an explicit user click (the CLI provisioner is invoked separately).
+ */
+export function buildNetworkSetupGuide(network = {}, tailscale = {}) {
+ const facts = deriveSetupFacts(network, tailscale);
+ const { trustedHttpsActive, canActivate, trustedUrl, pendingTrustedUrl, currentDnsName, canProvision } = facts;
+ const steps = [
+ installStep(facts),
+ connectStep(facts),
+ magicDnsStep(facts),
+ certStep(facts),
+ activateStep(facts),
];
const nextStep = trustedHttpsActive
diff --git a/server/lib/networkExposure.test.js b/server/lib/networkExposure.test.js
index dba3c16100..80b002c66e 100644
--- a/server/lib/networkExposure.test.js
+++ b/server/lib/networkExposure.test.js
@@ -257,6 +257,43 @@ describe('networkExposure.buildNetworkSetupGuide', () => {
});
});
+ it('blocks the certificate step with no action while the sandboxed CLI cannot reach MagicDNS', () => {
+ const guide = buildNetworkSetupGuide(baseNetwork, {
+ available: true,
+ running: false,
+ sandboxed: true,
+ });
+
+ expect(guide.steps.find((step) => step.id === 'https-cert')).toMatchObject({
+ status: 'blocked',
+ detail: expect.stringContaining('brew install tailscale'),
+ action: null,
+ });
+ });
+
+ it('explains that a matching certificate still needs Tailscale connected before activation', () => {
+ const guide = buildNetworkSetupGuide({
+ ...baseNetwork,
+ cert: {
+ ...baseNetwork.cert,
+ provisioned: true,
+ provisionedMode: 'tailscale',
+ provisionedHost: 'host-alpha.example-tailnet.ts.net',
+ },
+ }, {
+ available: true,
+ running: false,
+ sandboxed: false,
+ });
+
+ expect(guide.steps.find((step) => step.id === 'https-cert')).toMatchObject({ status: 'complete', action: null });
+ expect(guide.steps.find((step) => step.id === 'activate-https')).toMatchObject({
+ status: 'blocked',
+ detail: 'Connect Tailscale and confirm its current MagicDNS name before launching the trusted URL.',
+ action: null,
+ });
+ });
+
it('names a stale certificate hostname before offering reprovisioning', () => {
const guide = buildNetworkSetupGuide({
...baseNetwork,