hownz

<!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Admin: Developer Guide</title> <meta name="description" content="Technical guide for developers and administrators of hownz.com. Learn how to package and distribute the NPM CLI tool, troubleshoot common issues, and use all command-line options."> <meta name="keywords" content="hownz cli, npm package, developer guide, admin guide, command-line tool, text cleaner cli, node.js cli, TAR_BAD_ARCHIVE"> <meta name="robots" content="index, follow"> <link rel="stylesheet" href="index.css" /> <link rel="preconnect" href="https://fonts.googleapis.com"> <link rel="preconnect" href="httpss://fonts.gstatic.com" crossorigin> <link href="https://fonts.googleapis.com/css2?family=Roboto:wght@400;500;700&family=Inconsolata:wght@400&display=swap" rel="stylesheet"> <script type="application/ld+json"> { "@context": "https://schema.org", "@graph": [ { "@type": "Article", "headline": "Admin & Developer Guide for hownz.com", "description": "Technical guide for developers and administrators of hownz.com. Learn how to package and distribute the NPM CLI tool, troubleshoot common issues, and use all command-line options.", "image": "https://hownz.com/android-chrome-512x512.png", "author": { "@type": "Organization", "name": "hownz.com", "url": "https://hownz.com/" }, "publisher": { "@type": "Organization", "name": "hownz.com", "logo": { "@type": "ImageObject", "url": "https://hownz.com/android-chrome-512x512.png" } }, "datePublished": "2024-07-26", "mainEntityOfPage": { "@type": "WebPage", "@id": "https://hownz.com/admin.html" } }, { "@type": "BreadcrumbList", "itemListElement": [ { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://hownz.com/" }, { "@type": "ListItem", "position": 2, "name": "Admin & Developer Guide", "item": "https://hownz.com/admin.html" } ] }, { "@type": "FAQPage", "mainEntity": [ { "@type": "Question", "name": "How do I distribute the hownz NPM package?", "acceptedAnswer": { "@type": "Answer", "text": "You can either publish the package to the public NPM registry using 'npm run publish:npm', or you can host the generated .tgz file (created with 'npm pack') on your own website for direct installation." } }, { "@type": "Question", "name": "What does the 'npm error TAR_BAD_ARCHIVE' mean?", "acceptedAnswer": { "@type": "Answer", "text": "This error typically occurs when installing from a URL. It means npm received an HTML error page (like a 404 Not Found) instead of the expected .tgz package file, indicating the URL is incorrect or the file is missing." } }, { "@type": "Question", "name": "How can I add language-specific or emoji characters when using the CLI?", "acceptedAnswer": { "@type": "Answer", "text": "You can use the '--lang' flag to include additional language characters from the app.json dictionary and the '--emojis' flag to include emoji characters from the admin.json dictionary." } } ] } ] } </script> </head> <body> <div id="root"> <header class="site-header"> <div class="site-header-container"> <div class="header-left-side"> <div class="site-logo"> <a href="index.html">hownz.com</a> </div> <a href="hello.html" id="btn-hello-world" class="btn btn-special">Hello World!</a> </div> <div id="nav-wrapper" class="nav-wrapper"> <div class="header-actions"> <a href="coins.html" class="btn btn-rewards-info">Rewards info</a> <div id="logged-in-controls" class="hidden"> <div class="coin-balance" title="Coins"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor" width="24" height="24"><path d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm0 18c-4.41 0-8-3.59-8-8s3.59-8 8-8 8 3.59 8 8-3.59 8-8 8zm-1-12h2v2h-2v-2zm-2 4h6v2H9v-2zm8-2c0-2.21-1.79-4-4-4s-4 1.79-4 4h2c0-1.1.9-2 2-2s2 .9 2 2h-2c-2.21 0-4 1.79-4 4s1.79 4 4 4 4-1.79 4-4h-2c0 1.1-.9 2-2 2s-2-.9-2-2h4c0-2.21-1.79-4-4-4z" /></svg> <span id="coin-balance-display">0</span> </div> <button id="btn-logout" class="btn-logout">Logout</button> </div> <div id="logged-out-controls" class="header-login-container"> <form id="header-login-form" class="header-login-form"> <input type="text" id="login-username" placeholder="account" required maxLength="5" autoCapitalize="none" /> <input type="password" id="login-password" placeholder="password" required maxLength="5" autoCapitalize="none" /> <button type="submit" class="btn-login-register">Login/Register</button> <a href="index.html#settings" class="settings-icon" title="Settings"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor" width="24" height="24"> <path d="M19.43 12.98c.04-.32.07-.64.07-.98s-.03-.66-.07-.98l2.11-1.65c.19-.15.24-.42.12-.64l-2-3.46c-.12-.22-.39-.3-.61-.22l-2.49 1c-.52-.4-1.08-.73-1.69-.98l-.38-2.65C14.46 2.18 14.25 2 14 2h-4c-.25 0-.46.18-.49.42l-.38 2.65c-.61.25-1.17.59-1.69-.98l-2.49-1c-.23-.09-.49 0-.61.22l-2 3.46c-.13.22-.07.49.12.64l2.11 1.65c-.04.32-.07.65-.07.98s.03.66.07.98l-2.11 1.65c-.19.15-.24-.42-.12-.64l2 3.46c.12.22.39.3.61-.22l2.49 1c.52.4 1.08.73 1.69.98l.38 2.65c.03.24.24.42.49.42h4c.25 0 .46-.18.49.42l.38 2.65c.61-.25 1.17.59 1.69.98l2.49 1c.23-.09.49 0 .61.22l2-3.46c.12-.22-.07.49-.12-.64l-2.11-1.65zM12 15.5c-1.93 0-3.5-1.57-3.5-3.5s1.57-3.5 3.5-3.5 3.5 1.57 3.5 3.5-1.57 3.5-3.5 3.5z"/> </svg> </a> </form> <p class="login-hint">Account & Password: 5 small English letters.</p> </div> </div> </div> </div> </header> <div class="app-container"> <div class="admin-content-page"> <h1><span role="img" aria-label="Toolbox">🛠️</span> Admin & Developer Guide</h1> <p class="admin-intro-text"> This page is a technical reference for the site owner. It explains how to package and distribute the command-line tool and provides a reference for its usage and core script. </p> <section class="admin-guide-section"> <h2>Distributing the NPM Package</h2> <p class="admin-section-intro">There are two primary ways to make the <code>hownz</code> tool available for installation. The method you choose determines the command users will run.</p> <div class="install-options-grid"> <div class="install-option-item admin-option"> <h3>Option A: Publish to Public NPM Registry</h3> <p>This is the standard method for distributing public packages. It makes your tool discoverable on <a href="https://www.npmjs.com/package/hownz/v/2.0.0" target="_blank" rel="noopener noreferrer">npmjs.com</a> and installable for anyone.</p> <h4>Steps to Publish:</h4> <ol> <li><strong>Login to NPM:</strong> If this is your first time, run <code>npm adduser</code>. Otherwise, run <code>npm login</code>.</li> <li><strong>Publish:</strong> Run the command <code>npm run publish:npm</code> from your project directory. This script is an alias for `npm publish --access public`.</li> </ol> <h4>User Installation Command:</h4> <div class="npm-command-wrapper"><code class="npm-command">npm install -g hownz</code></div> </div> <div class="install-option-item admin-option"> <h3>Option B: Host Package on This Website</h3> <p>This method allows users to install the package directly from your server. It's useful for providing a specific version or when the NPM registry is not an option.</p> <h4>Steps to Host:</h4> <ol> <li><strong>Create the Package:</strong> Run the command <code>npm pack</code> in your project directory.</li> <li><strong>Get the File:</strong> This creates a file named <code>hownz-2.0.0.tgz</code>.</li> <li><strong>Upload:</strong> Upload this <code>.tgz</code> file to the root directory of your website, making it available at <code>https://hownz.com/hownz-2.0.0.tgz</code>.</li> </ol> <h4>User Installation Command:</h4> <div class="npm-command-wrapper"><code class="npm-command">npm install -g https://hownz.com/hownz-2.0.0.tgz</code></div> </div> </div> </section> <section class="admin-guide-section"> <h2>Troubleshooting Installation</h2> <div class="install-options-grid"> <div class="install-option-item admin-option" style="grid-column: 1 / -1;"> <h3>Diagnosing `npm error TAR_BAD_ARCHIVE`</h3> <p>This error means the install URL is wrong. It happens when npm gets an HTML error page (like "404 Not Found") instead of the expected <code>.tgz</code> package file. </p> <h4>To fix this, check three things:</h4> <ol> <li><strong>Verify URL:</strong> Open the installation URL (e.g., <code>https://hownz.com/hownz-2.0.0.tgz</code>) in a browser. It must start a file download, not show a webpage.</li> <li><strong>Check Filename & Version:</strong> The filename must exactly match the version in your <code>package.json</code>. If you update the version, run <code>npm pack</code> and upload the new file.</li> <li><strong>Confirm Location:</strong> The <code>.tgz</code> file must be in the website's root directory to be accessible at the direct URL.</li> </ol> </div> </div> </section> <section class="admin-guide-section"> <h2>Using the Command-Line Tool (CLI)</h2> <p class="admin-section-intro">Once installed globally, the <code>hownz</code> command can be used in any terminal. It's highly flexible, allowing you to clean text directly, pipe content from other commands (like <code>echo</code> or <code>curl</code>), or process entire files. By default, it prints to the console, but its behavior can be modified with the flags below.</p> <div class="cli-commands-grid"> <div class="cli-command-item"><code>hownz "text"</code><p>Cleans a string → console output.</p></div> <div class="cli-command-item"><code>hownz -a "text"</code><p>Cleans a string → random .txt file.</p></div> <div class="cli-command-item"><code>echo "text" | hownz</code><p>Cleans piped text → random .txt file.</p></div> <div class="cli-command-item"><code>hownz < in.txt --here</code><p>Redirects `in.txt` as input; `--here` forces output to console, ideal for piping to other commands.</p></div> <div class="cli-command-item"><code>hownz -s < article.txt</code><p>Summarizes `article.txt` using the Gemini API (`-s`); automatically saves the output to a new file.</p></div> <div class="cli-command-item"><code>hownz -m "text"</code><p>Marks unrecognized chars with '#'.</p></div> <div class="cli-command-item"><code>hownz -l "text"</code><p>Includes language characters (app.json).</p></div> <div class="cli-command-item"><code>hownz -e "text"</code><p>Includes emoji characters (admin.json).</p></div> <div class="cli-command-item"><code>hownz --list</code><p>Shows all contraction replacements.</p></div> <div class="cli-command-item"><code>hownz -t</code><p>Shows all approved characters.</p></div> <div class="cli-command-item"><code>hownz --lg</code><p>Shows language dictionary (app.json).</p></div> <div class="cli-command-item"><code>hownz --ej</code><p>Shows emoji dictionary (admin.json).</p></div> <div class="cli-command-item"><code>hownz -v</code><p>Shows the current version number.</p></div> <div class="cli-command-item"><code>hownz -h</code><p>Displays the detailed help guide.</p></div> <div class="cli-command-item"><code>hownz "text with ñ and ö" -lm</code><p>Combines language (`-l`) and mark (`-m`) flags to process special characters.</p></div> <div class="cli-command-item"><code>curl -sL ip.im | hownz -s --here</code><p>Pipes web content from `curl` to be summarized by the AI and prints the result to the console.</p></div> <div class="cli-command-item"><code>hownz "text with emoji 😀"</code><p>Removes emojis and other unrecognized characters by default.</p></div> <div class="cli-command-item"><code>cat log.txt | hownz -s -o summary.txt</code><p>Pipes a local file to the AI summarizer (`-s`) and saves the output to a specified file (`-o`).</p></div> <div class="cli-command-item"><code>hownz < document.txt</code><p>Cleans a file's content and saves it to a new, randomly named .txt file.</p></div> <div class="cli-command-item"><code>hownz "some text" -o result.txt</code><p>Cleans a string and saves it to the specified 'result.txt' file.</p></div> </div> </section> <section class="admin-guide-section"> <h2>Core Application Script Reference</h2> <pre class="admin-code-block"><code id="script-display-container">Loading script...</code></pre> </section> </div> </div> <footer class="site-footer-main"> <div id="footer-links-container" class="footer-links"> </div> <button id="btn-claim-install" class="btn btn-claim-install visually-hidden">Explore</button> <div class="site-search-container"> <form id="site-search-form" class="site-search-form"> <input type="search" id="site-search-input" class="site-search-input" placeholder="Search across our network..."> <button type="submit" class="site-search-button" aria-label="Search"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor" width="20" height="20"><path d="M15.5 14h-.79l-.28-.27C14.41 12.59 15 11.11 15 9.5 15 5.91 12.09 3 8.5 3S2 5.91 2 9.5 4.91 16 8.5 16c1.61 0 3.09-.59 4.23-1.57l.27.28v.79l5 4.99L19.49 19l-4.99-5zm-7 0C6.01 14 4 11.99 4 9.5S6.01 5 8.5 5 13 7.01 13 9.5 10.99 14 8.5 14z"/></svg> </button> </form> </div> <div class="footer-banner"> <div class="footer-v-stack"> <div id="date-time-display"> <span id="time-display" class="time"></span> <span id="date-display" class="date"></span> </div> <a href="https://mfatnz.com" id="ip-ad-link"> <img src="https://ip.im/img" alt="My IP Address" width="185" height="50" /> </a> </div> <div class="footer-banner-text-content" style="text-align: left;"> <p style="margin: 0 0 0.5rem 0;"><span role="img" aria-label="Coin">🟡</span> Your progress is worth celebrating. Earn <strong>Dopamine Dash Coins</strong> as part of a fair system designed to support your <strong>motivation</strong>.</p> <p style="margin: 0;">A free, non-commercial tool created in support of mfatnz.com Independent Initiative. A simple tool for the developer community.</p> </div> </div> </footer> </div> <script type="module"> // The script for admin.html page itself. document.addEventListener('DOMContentLoaded', () => { const updateDateTime = () => { const timeDisplay = document.getElementById('time-display'); const dateDisplay = document.getElementById('date-display'); if (!timeDisplay || !dateDisplay) return; const now = new Date(); const hours = String(now.getHours()).padStart(2, '0'); const minutes = String(now.getMinutes()).padStart(2, '0'); timeDisplay.textContent = `${hours}:${minutes}`; const options = { year: 'numeric', month: 'long', day: 'numeric' }; dateDisplay.textContent = now.toLocaleDateString(undefined, options); }; updateDateTime(); setInterval(updateDateTime, 60000); const footerLinks = [{href: "https://mfatnz.com/", text: "mfatnz.com"}, {href: "https://actnz.com", text: "actnz.com"}, {href: "https://irdnz.com", text: "irdnz.com"}, {href: "https://hownz.com", text: "hownz.com"}, {href: "coins.html", text: "Rewards info"}]; const dom = { footerLinksContainer: document.getElementById('footer-links-container'), siteSearchForm: document.getElementById('site-search-form'), siteSearchInput: document.getElementById('site-search-input'), scriptDisplayContainer: document.getElementById('script-display-container') }; if (dom.footerLinksContainer) { dom.footerLinksContainer.innerHTML = footerLinks.map(link => `<a href="${link.href}" target="_blank" rel="noopener noreferrer">${link.text}</a>`).join(''); } if (dom.siteSearchForm && dom.siteSearchInput) { dom.siteSearchForm.addEventListener('submit', e => { e.preventDefault(); const query = dom.siteSearchInput.value.trim(); if (!query) return; const sites = ['mfatnz.com', 'actnz.com', 'irdnz.com', 'hownz.com']; const siteQuery = sites.map(site => `site:${site}`).join(' OR '); const fullQuery = `${query} ${siteQuery}`; const searchUrl = `https://www.google.com/search?q=${encodeURIComponent(fullQuery)}`; window.open(searchUrl, '_blank'); }); } // Fetch and display the main script content for reference fetch('cli.js') .then(response => { if (!response.ok) { throw new Error(`HTTP error! status: ${response.status}`); } return response.text(); }) .then(scriptContent => { if (dom.scriptDisplayContainer) { dom.scriptDisplayContainer.textContent = scriptContent.trim(); } }) .catch(error => { console.error('Error fetching script content:', error); if (dom.scriptDisplayContainer) { dom.scriptDisplayContainer.textContent = 'Error loading script for display.'; } }); }); </script> </body> </html>